> 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

## Create Workflow

> Creates a new workflow. When a shipment\_id is provided, origin, destination and packages are not required (unless blueprint requires crossdock). Blueprint is required (either blueprint\_code or blueprint\_id).

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"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."}}},"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"}}},"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)"}}},"Workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"current_status":{"type":"string"},"blueprint":{"type":"object","properties":{"code":{"type":"string"},"id":{"type":"integer"}}},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}},"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":{"/workflows":{"post":{"tags":["Workflows"],"summary":"Create Workflow","description":"Creates a new workflow. When a shipment_id is provided, origin, destination and packages are not required (unless blueprint requires crossdock). Blueprint is required (either blueprint_code or blueprint_id).","operationId":"createWorkflow","requestBody":{"description":"Workflow object","required":true,"content":{"application/json":{"schema":{"type":"object","description":"Se debe enviar `blueprint_code` **o** `blueprint_id` (al menos uno; no ambos requeridos). Si se envía `shipment_id`, no hace falta `origin`/`destination`/`packages` (se toman del envío), salvo que el blueprint requiera `crossdock`.\n","properties":{"blueprint_code":{"type":"string","description":"Código del blueprint. Requerido si no se envía `blueprint_id`. Debe existir en workflow_blueprints para la organización."},"blueprint_id":{"type":"integer","description":"Blueprint ID (required if blueprint_code is not provided, must exist in workflow_blueprints table for the organization)"},"shipment_id":{"type":"integer","description":"Shipment ID (optional, if provided, origin, destination and packages are not required unless blueprint requires crossdock, must exist in shipments table for the organization)"},"external_reference":{"type":"string","description":"External reference for the workflow (optional)"},"origin":{"$ref":"#/components/schemas/AddressInput","description":"Origin address (required if shipment_id is not provided and blueprint requires it, can be address id, place_id, or full address object)"},"crossdock":{"$ref":"#/components/schemas/AddressInput","description":"Crossdock address (required if blueprint requires it, can be address id, place_id, or full address object)"},"destination":{"$ref":"#/components/schemas/AddressInput","description":"Destination address (required if shipment_id is not provided and blueprint requires it, can be address id, place_id, or full address object)"},"packages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/PackageInput"},"description":"Packages array (required if shipment_id is not provided and blueprint requires it, minimum 1 package)"},"settings":{"type":"array","items":{"type":"object","properties":{"step_name":{"type":"string","description":"Step name (optional, must exist in workflow_blueprint_steps for the blueprint)"},"notes":{"type":"string","description":"Step notes (optional)"},"is_self_assignable":{"type":"boolean","description":"Whether step tasks can be self-assigned (optional)"},"service_time_seconds":{"type":"integer","minimum":1,"description":"Service time in seconds for step tasks (optional, minimum: 1)"},"use_as_starting_point":{"type":"boolean","description":"Whether step should be used as starting point (optional)"},"use_as_ending_point":{"type":"boolean","description":"Whether step should be used as ending point (optional)"},"requirements_start":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true,"description":"Requirements to start step tasks (optional)"},"requirements_complete":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true,"description":"Requirements to complete step tasks (optional)"},"requirements_fail":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true,"description":"Requirements to fail step tasks (optional)"},"time_windows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"},"nullable":true,"description":"Time windows for step tasks (optional)"},"should_complete_after":{"type":"string","format":"date-time","description":"Earliest completion time for step tasks (optional, format: Y-m-d H:i:s)"},"should_complete_before":{"type":"string","format":"date-time","description":"Latest completion time for step tasks (optional, format: Y-m-d H:i:s)"}}},"description":"Settings for workflow steps (optional)"}}}}}},"responses":{"201":{"description":"Workflow created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"workflow":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workflow"}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## Get Workflow

> Gets a workflow by ULID

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"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":{"Workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"current_status":{"type":"string"},"blueprint":{"type":"object","properties":{"code":{"type":"string"},"id":{"type":"integer"}}},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}},"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":{"/workflows/{workflow}":{"get":{"tags":["Workflows"],"summary":"Get Workflow","description":"Gets a workflow by ULID","operationId":"getWorkflow","parameters":[{"name":"workflow","in":"path","required":true,"description":"Workflow ULID","schema":{"type":"string","format":"ulid"}},{"name":"include_tasks","in":"query","schema":{"type":"boolean"},"description":"Whether to include tasks in the response (optional)"}],"responses":{"200":{"description":"Workflow retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## Update Workflow

> Updates an existing workflow

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"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":{"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)"}}},"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."}}},"Workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"current_status":{"type":"string"},"blueprint":{"type":"object","properties":{"code":{"type":"string"},"id":{"type":"integer"}}},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}},"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":{"/workflows/{workflow}":{"put":{"tags":["Workflows"],"summary":"Update Workflow","description":"Updates an existing workflow","operationId":"updateWorkflow","parameters":[{"name":"workflow","in":"path","required":true,"description":"Workflow ULID","schema":{"type":"string","format":"ulid"}}],"requestBody":{"description":"Workflow object","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"array","items":{"type":"object","properties":{"step_name":{"type":"string","description":"Step name (optional, must exist in workflow_blueprint_steps for the blueprint)"},"notes":{"type":"string","description":"Step notes (optional)"},"is_self_assignable":{"type":"boolean","description":"Whether step tasks can be self-assigned (optional)"},"service_time_seconds":{"type":"integer","minimum":1,"description":"Service time in seconds for step tasks (optional, minimum: 1)"},"use_as_starting_point":{"type":"boolean","description":"Whether step should be used as starting point (optional)"},"use_as_ending_point":{"type":"boolean","description":"Whether step should be used as ending point (optional)"},"requirements_start":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true,"description":"Requirements to start step tasks (optional)"},"requirements_complete":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true,"description":"Requirements to complete step tasks (optional)"},"requirements_fail":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"nullable":true,"description":"Requirements to fail step tasks (optional)"},"time_windows":{"type":"array","items":{"$ref":"#/components/schemas/TimeWindow"},"nullable":true,"description":"Time windows for step tasks (optional)"},"should_complete_after":{"type":"string","format":"date-time","description":"Earliest completion time for step tasks (optional, format: Y-m-d H:i:s)"},"should_complete_before":{"type":"string","format":"date-time","description":"Latest completion time for step tasks (optional, format: Y-m-d H:i:s)"}}},"description":"Settings for workflow steps (optional)"},"crossdock":{"$ref":"#/components/schemas/AddressInput","description":"Crossdock address (optional, can be address id, place_id, or full address object, required if blueprint requires it)"}}}}}},"responses":{"200":{"description":"Workflow updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## Cancel Workflow

> Cancels a workflow by ULID. Automatically cancels all pending tasks.

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Workflows","description":"Gestión de workflows"}],"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":{"Workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"current_status":{"type":"string"},"blueprint":{"type":"object","properties":{"code":{"type":"string"},"id":{"type":"integer"}}},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}},"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":{"/workflows/{workflow}/cancel":{"post":{"tags":["Workflows"],"summary":"Cancel Workflow","description":"Cancels a workflow by ULID. Automatically cancels all pending tasks.","operationId":"cancelWorkflow","parameters":[{"name":"workflow","in":"path","required":true,"description":"Workflow 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":"Workflow cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"workflow":{"$ref":"#/components/schemas/Workflow"}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## Esquemas

## The Workflow object

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"components":{"schemas":{"Workflow":{"type":"object","properties":{"id":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"current_status":{"type":"string"},"blueprint":{"type":"object","properties":{"code":{"type":"string"},"id":{"type":"integer"}}},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}},"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 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"}}}}}}
```


---

# 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/workflows.md?ask=<question>&goal=<endgoal>
```

`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.