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

# Workflows

## Endpoints

## Crear workflow

> Crea un nuevo workflow. Requiere \`blueprint\_code\` o \`blueprint\_id\`.\
> \
> Si se envía \`shipment\_id\`, el workflow se crea a partir de un envío existente y origin/destination/packages se toman del envío (salvo que el blueprint requiera \`crossdock\`).

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AddressInput":{"description":"Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**:\n\n| Modo | Qué enviar | Comportamiento |\n|------|-----------|----------------|\n| **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"title":"1. Reutilizar dirección existente (id)","description":"Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.","required":["id"],"properties":{"id":{"description":"ID de una dirección existente.","type":"string"}},"type":"object"},"AddressByPlaceInput":{"title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.","required":["place_id"],"properties":{"place_id":{"description":"ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.","type":"string"}},"type":"object"},"AddressNewInput":{"title":"3. Dirección nueva (objeto completo)","description":"Crea una dirección nueva. La ubicación se puede indicar de dos formas:\n- **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** envía `city`, `state` y `country` (código ISO).","required":["name","street","street_number"],"properties":{"name":{"description":"Nombre del destinatario/remitente.","type":"string","maxLength":100},"street":{"description":"Nombre de la calle.","type":"string","maxLength":100},"street_number":{"description":"Altura/número.","type":"string","maxLength":10},"floor":{"description":"Piso (opcional).","type":"string","maxLength":5,"nullable":true},"apartment":{"description":"Departamento (opcional).","type":"string","maxLength":10,"nullable":true},"reference":{"description":"Referencia adicional (opcional).","type":"string","maxLength":255,"nullable":true},"city_id":{"description":"ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.","type":"integer"},"city":{"description":"Nombre de la ciudad. Obligatorio si no se envía `city_id`.","type":"string"},"state_id":{"description":"ID interno de la provincia/estado (opcional).","type":"integer"},"state":{"description":"Nombre de la provincia/estado.","type":"string"},"country_id":{"description":"ID interno del país (opcional).","type":"integer"},"country":{"description":"Código ISO del país (ej: AR, MX, CL).","type":"string"},"zipcode":{"description":"Código postal (opcional).","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164 (opcional).","type":"string","nullable":true},"email":{"description":"Email de contacto (opcional).","type":"string","format":"email","nullable":true},"document_type":{"description":"Código del tipo de documento (opcional).","type":"string","nullable":true},"document_number":{"description":"Número de documento (obligatorio si se envía `document_type`).","type":"string","nullable":true},"geo_latitude":{"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":90,"minimum":-90,"nullable":true},"geo_longitude":{"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":180,"minimum":-180,"nullable":true}},"type":"object"},"WorkflowSetting":{"description":"Configuración de un paso del workflow (step settings)","properties":{"step_code":{"description":"Código del step del blueprint.","type":"string"},"requirements_start":{"description":"Requisitos personalizados para iniciar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_complete":{"description":"Requisitos personalizados para completar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_fail":{"description":"Requisitos personalizados para fallar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"PackageInput":{"description":"Paquete a incluir en el envío o tarea. Cada medida (peso y dimensiones) se puede enviar de dos formas:\n- **Valor normalizado:** `grams` (gramos), `length`/`width`/`height` (centímetros). El sistema lo guarda tal cual.\n- **Valor con unidad:** `original_weight` + `weight_unit` (y los `original_*` + `*_unit` para dimensiones). El sistema normaliza automáticamente y conserva el valor original.\n\n**Si se envía `id`:** se reutiliza un paquete existente y los demás campos no son necesarios.\n\n**Si no se envía `id`:** `length`, `width` y `height` son obligatorios. El peso debe enviarse como `grams` **o** `original_weight` + `weight_unit`.\n\nUnidades soportadas:\n- Peso: `g`, `kg`, `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"},"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °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"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}},"paths":{"/workflows":{"post":{"tags":["Workflows"],"summary":"Crear workflow","description":"Crea un nuevo workflow. Requiere `blueprint_code` o `blueprint_id`.\n\nSi se envía `shipment_id`, el workflow se crea a partir de un envío existente y origin/destination/packages se toman del envío (salvo que el blueprint requiera `crossdock`).","operationId":"createWorkflow","requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"blueprint_code":{"description":"Código del blueprint. Requerido si no se envía `blueprint_id`.","type":"string"},"blueprint_id":{"description":"ID del blueprint. Requerido si no se envía `blueprint_code`.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"shipment_id":{"description":"ID del envío existente. Si se envía, origin/destination/packages se toman del envío.","type":"integer","nullable":true},"crossdock":{"$ref":"#/components/schemas/AddressInput"},"settings":{"description":"Configuraciones personalizadas por step del blueprint.","type":"array","items":{"$ref":"#/components/schemas/WorkflowSetting"}},"packages":{"description":"Paquetes (requerido si el blueprint lo indica y no se envía shipment_id).","type":"array","items":{"$ref":"#/components/schemas/PackageInput"}}},"type":"object"}}}},"responses":{"201":{"description":"Workflow creado","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"workflow":{"$ref":"#/components/schemas/Workflow"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"422":{"description":"Error de validación"}}}}}}
```

## Obtener workflow

> Obtiene los detalles de un workflow. Por defecto retorna el resumen; para incluir las tareas enviá \`include\_tasks=1\`.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °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"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}},"paths":{"/workflows/{workflow}":{"get":{"tags":["Workflows"],"summary":"Obtener workflow","description":"Obtiene los detalles de un workflow. Por defecto retorna el resumen; para incluir las tareas enviá `include_tasks=1`.","operationId":"getWorkflow","parameters":[{"name":"workflow","in":"path","description":"ID del workflow","required":true,"schema":{"type":"integer"}},{"name":"include_tasks","in":"query","description":"Si se envía con valor `1`, incluye las tareas del workflow en la respuesta.","required":false,"schema":{"type":"integer","enum":[0,1]}}],"responses":{"200":{"description":"Workflow obtenido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Workflow no encontrado"}}}}}}
```

## Actualizar workflow

> Actualiza la configuración de un workflow existente (settings y crossdock).

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AddressInput":{"description":"Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**:\n\n| Modo | Qué enviar | Comportamiento |\n|------|-----------|----------------|\n| **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"title":"1. Reutilizar dirección existente (id)","description":"Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.","required":["id"],"properties":{"id":{"description":"ID de una dirección existente.","type":"string"}},"type":"object"},"AddressByPlaceInput":{"title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.","required":["place_id"],"properties":{"place_id":{"description":"ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.","type":"string"}},"type":"object"},"AddressNewInput":{"title":"3. Dirección nueva (objeto completo)","description":"Crea una dirección nueva. La ubicación se puede indicar de dos formas:\n- **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** envía `city`, `state` y `country` (código ISO).","required":["name","street","street_number"],"properties":{"name":{"description":"Nombre del destinatario/remitente.","type":"string","maxLength":100},"street":{"description":"Nombre de la calle.","type":"string","maxLength":100},"street_number":{"description":"Altura/número.","type":"string","maxLength":10},"floor":{"description":"Piso (opcional).","type":"string","maxLength":5,"nullable":true},"apartment":{"description":"Departamento (opcional).","type":"string","maxLength":10,"nullable":true},"reference":{"description":"Referencia adicional (opcional).","type":"string","maxLength":255,"nullable":true},"city_id":{"description":"ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.","type":"integer"},"city":{"description":"Nombre de la ciudad. Obligatorio si no se envía `city_id`.","type":"string"},"state_id":{"description":"ID interno de la provincia/estado (opcional).","type":"integer"},"state":{"description":"Nombre de la provincia/estado.","type":"string"},"country_id":{"description":"ID interno del país (opcional).","type":"integer"},"country":{"description":"Código ISO del país (ej: AR, MX, CL).","type":"string"},"zipcode":{"description":"Código postal (opcional).","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164 (opcional).","type":"string","nullable":true},"email":{"description":"Email de contacto (opcional).","type":"string","format":"email","nullable":true},"document_type":{"description":"Código del tipo de documento (opcional).","type":"string","nullable":true},"document_number":{"description":"Número de documento (obligatorio si se envía `document_type`).","type":"string","nullable":true},"geo_latitude":{"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":90,"minimum":-90,"nullable":true},"geo_longitude":{"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":180,"minimum":-180,"nullable":true}},"type":"object"},"WorkflowSetting":{"description":"Configuración de un paso del workflow (step settings)","properties":{"step_code":{"description":"Código del step del blueprint.","type":"string"},"requirements_start":{"description":"Requisitos personalizados para iniciar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_complete":{"description":"Requisitos personalizados para completar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true},"requirements_fail":{"description":"Requisitos personalizados para fallar.","type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °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"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}},"paths":{"/workflows/{workflow}":{"put":{"tags":["Workflows"],"summary":"Actualizar workflow","description":"Actualiza la configuración de un workflow existente (settings y crossdock).","operationId":"updateWorkflow","parameters":[{"name":"workflow","in":"path","description":"ID del workflow","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"crossdock":{"$ref":"#/components/schemas/AddressInput"},"settings":{"description":"Configuraciones personalizadas por step.","type":"array","items":{"$ref":"#/components/schemas/WorkflowSetting"}}},"type":"object"}}}},"responses":{"200":{"description":"Workflow actualizado","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"workflow":{"$ref":"#/components/schemas/Workflow"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Workflow no encontrado"},"422":{"description":"Error de validación"}}}}}}
```

## Cancelar workflow

> Cancela un workflow y todas sus tareas pendientes.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °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"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}},"paths":{"/workflows/{workflow}/cancel":{"post":{"tags":["Workflows"],"summary":"Cancelar workflow","description":"Cancela un workflow y todas sus tareas pendientes.","operationId":"cancelWorkflow","parameters":[{"name":"workflow","in":"path","description":"ID del workflow","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Workflow cancelado","content":{"application/json":{"schema":{"properties":{"data":{"properties":{"workflow":{"$ref":"#/components/schemas/Workflow"}},"type":"object"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Workflow no encontrado"}}}}}}
```

## Esquemas

## The Workflow object

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Workflow":{"description":"Workflow que agrupa las tareas de un envío o proceso logístico","properties":{"id":{"description":"Identificador del workflow.","type":"integer"},"external_reference":{"description":"Referencia externa del workflow.","type":"string","nullable":true},"current_status":{"description":"Estado actual del workflow.","type":"string"},"blueprint":{"description":"Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.","properties":{"id":{"type":"integer"},"code":{"type":"string"},"steps":{"description":"Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"data":{"description":"Datos adicionales asociados al workflow (estructura variable según el blueprint).","type":"object","nullable":true},"tasks":{"description":"Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/Task"}},{"type":"array","items":{"$ref":"#/components/schemas/TaskSummary"}}]}},"type":"object"},"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °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"},"TaskSummary":{"description":"Resumen reducido de una tarea, retornado en contextos de workflow sin include_tasks=1.","properties":{"id":{"description":"ULID de la tarea.","type":"string"},"internal_id":{"description":"ID numérico interno de la tarea.","type":"integer"},"carrier":{"properties":{"id":{"type":"integer"}},"type":"object"},"shipment":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"properties":{"id":{"type":"integer"},"reference":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true}},"type":"object","nullable":true},"step":{"properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de tipo pickup.","type":"boolean"},"status":{"properties":{"id":{"type":"integer"},"code":{"type":"string"}},"type":"object"}},"type":"object"}}}}
```

## The Task object

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Task":{"description":"Tarea de entrega o pickup","properties":{"id":{"description":"Identificador de la tarea.","type":"string"},"internal_id":{"description":"ID interno de la tarea.","type":"integer"},"grouping_hash":{"description":"Hash que agrupa tareas relacionadas del mismo workflow.","type":"string"},"client_code":{"description":"Código de cliente asociado a la tarea.","type":"string","nullable":true},"carrier":{"description":"Carrier (organización transportista) propietaria de la tarea.","properties":{"id":{"type":"integer"},"subdomain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"step":{"description":"Paso del workflow al que pertenece la tarea.","properties":{"name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true},"complete_actions":{"type":"array","items":{"type":"object"}},"fail_actions":{"type":"array","items":{"type":"object"}},"cancel_actions":{"type":"array","items":{"type":"object"}}},"type":"object","nullable":true},"is_pickup":{"description":"Si la tarea es de pickup (retiro).","type":"boolean"},"status":{"description":"Estado actual de la tarea","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"},"address":{"$ref":"#/components/schemas/Address"},"recipient_name":{"description":"Nombre del destinatario.","type":"string","nullable":true},"notes":{"description":"Notas de la tarea.","type":"string","nullable":true},"is_self_assignable":{"description":"Si la tarea puede ser autoasignada.","type":"boolean"},"assigned_to_user":{"description":"Usuario asignado a la tarea","properties":{"id":{"type":"integer"},"firstname":{"type":"string"},"lastname":{"type":"string"}},"type":"object","nullable":true},"should_complete_after":{"description":"Fecha y hora mínima de completado.","type":"string","format":"date-time","nullable":true},"should_complete_before":{"description":"Fecha y hora máxima de completado.","type":"string","format":"date-time","nullable":true},"depends_on_task_ids":{"description":"IDs de las tareas de las que depende esta tarea.","type":"array","items":{"type":"string"}},"cost":{"description":"Costo asociado a la tarea.","type":"number","nullable":true},"service_time_seconds":{"description":"Tiempo de servicio en segundos.","type":"integer"},"requirements_start":{"description":"Requisitos para iniciar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_complete":{"description":"Requisitos para completar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"requirements_fail":{"description":"Requisitos para fallar la tarea.","type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"time_windows":{"description":"Ventanas de tiempo de la tarea.","type":"array","items":{"$ref":"#/components/schemas/TimeWindow"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"shipment":{"description":"Envío asociado a la tarea","properties":{"id":{"type":"integer"},"ulid":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"client_code":{"type":"string","nullable":true},"external_reference":{"type":"string","nullable":true},"declared_value":{"type":"number","nullable":true},"control_number":{"type":"string","nullable":true}},"type":"object","nullable":true},"workflow":{"description":"Workflow al que pertenece la tarea","properties":{"id":{"type":"integer"},"external_reference":{"type":"string","nullable":true},"step_in_workflow":{"type":"string","nullable":true},"blueprint":{"properties":{"type":{"type":"string"}},"type":"object"}},"type":"object","nullable":true},"merchant":{"oneOf":[{"$ref":"#/components/schemas/Merchant"}],"nullable":true},"merchant_id":{"description":"ID del comercio asociado.","type":"integer","nullable":true},"groupable_by_merchant":{"description":"Si la tarea puede agruparse por comercio.","type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Requirement":{"description":"Requisito a cumplir para iniciar, completar o fallar una tarea","properties":{"type":{"description":"Tipo de requisito.","type":"string"},"label":{"description":"Etiqueta del requisito.","type":"string"},"required":{"description":"Si el requisito es obligatorio.","type":"boolean"},"value":{"description":"Valor del requisito (puede ser string, número, booleano o null).","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"type":"object"},"TimeWindow":{"description":"Ventana de tiempo para la ejecución de una tarea","properties":{"from":{"description":"Inicio de la ventana de tiempo.","type":"string","format":"date-time"},"to":{"description":"Fin de la ventana de tiempo.","type":"string","format":"date-time"}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °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"}}}}
```