---
title: "Crear workflow"
method: POST
path: "/workflows"
tags: ["Workflows"]
---

# Crear workflow

`POST /workflows`

## Request

- Base URL: `https://mi-organizacion.routes.zipnova.app/api/v1`
- URL: `https://mi-organizacion.routes.zipnova.app/api/v1/workflows`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/zipnova/apis/zipnova-rutas-api-organizacional/docs/workflows/post.ts> (a function with typed inputs; its response is checked against the schema)

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

## Request body

- object
  - `blueprint_code` string: Código del blueprint. Requerido si no se envía `blueprint_id`.
  - `blueprint_id` integer: ID del blueprint. Requerido si no se envía `blueprint_code`.
  - `external_reference` string, nullable: Referencia externa del workflow.
  - `shipment_id` integer, nullable: ID del envío existente. Si se envía, origin/destination/packages se toman del envío.
  - `crossdock` union: Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**: | Modo | Qué enviar | Comportamiento | |------|-----------|----------------| | **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. | | **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. | | **3. Dirección nueva** | objeto completo | Crea una dirección nueva. | **Reglas de exclusión:** - `id` y `place_id` son excluyentes entre sí. - En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).
    - AddressByIdInput: Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.
      - `id` string, required: ID de una dirección existente.
    - AddressByPlaceInput: Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.
      - `place_id` string, required: ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.
    - AddressNewInput: Crea una dirección nueva. La ubicación se puede indicar de dos formas: - **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`). - **Por nombres:** envía `city`, `state` y `country` (código ISO).
      - `name` string, required: Nombre del destinatario/remitente.
      - `street` string, required: Nombre de la calle.
      - `street_number` string, required: Altura/número.
      - `floor` string, nullable: Piso (opcional).
      - `apartment` string, nullable: Departamento (opcional).
      - `reference` string, nullable: Referencia adicional (opcional).
      - `city_id` integer: ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.
      - `city` string: Nombre de la ciudad. Obligatorio si no se envía `city_id`.
      - `state_id` integer: ID interno de la provincia/estado (opcional).
      - `state` string: Nombre de la provincia/estado.
      - `country_id` integer: ID interno del país (opcional).
      - `country` string: Código ISO del país (ej: AR, MX, CL).
      - `zipcode` string, nullable: Código postal (opcional).
      - `phone` string, nullable: Teléfono en formato E.164 (opcional).
      - `email` string, email, nullable: Email de contacto (opcional).
      - `document_type` string, nullable: Código del tipo de documento (opcional).
      - `document_number` string, nullable: Número de documento (obligatorio si se envía `document_type`).
      - `geo_latitude` number, float, nullable: Latitud (opcional). Si se omite, se geocodifica desde la dirección.
      - `geo_longitude` number, float, nullable: Longitud (opcional). Si se omite, se geocodifica desde la dirección.
  - `settings` WorkflowSetting[]: Configuraciones personalizadas por step del blueprint.
    - `step_code` string: Código del step del blueprint.
    - `requirements_start` Requirement[], nullable: Requisitos personalizados para iniciar.
      - `type` string: Tipo de requisito.
      - `label` string: Etiqueta del requisito.
      - `required` boolean: Si el requisito es obligatorio.
      - `value` union: Valor del requisito (puede ser string, número, booleano o null).
        - string
        - number
        - boolean
    - `requirements_complete` Requirement[], nullable: Requisitos personalizados para completar.
      - `type` string: Tipo de requisito.
      - `label` string: Etiqueta del requisito.
      - `required` boolean: Si el requisito es obligatorio.
      - `value` union: Valor del requisito (puede ser string, número, booleano o null).
        - string
        - number
        - boolean
    - `requirements_fail` Requirement[], nullable: Requisitos personalizados para fallar.
      - `type` string: Tipo de requisito.
      - `label` string: Etiqueta del requisito.
      - `required` boolean: Si el requisito es obligatorio.
      - `value` union: Valor del requisito (puede ser string, número, booleano o null).
        - string
        - number
        - boolean
  - `packages` PackageInput[]: Paquetes (requerido si el blueprint lo indica y no se envía shipment_id).
    - `id` integer: ID del paquete existente. Si se envía, los demás campos no son necesarios.
    - `external_reference` string, nullable: Referencia externa (opcional).
    - `description` string, nullable: Descripción del paquete (opcional).
    - `label_code` string: Código de etiqueta del paquete.
    - `length` integer: Largo en centímetros (normalizado).
    - `width` integer: Ancho en centímetros (normalizado).
    - `height` integer: Alto en centímetros (normalizado).
    - `original_length` number: Largo en la unidad original.
    - `length_unit` 'cm' | 'm' | 'in' | 'ft': Unidad del largo original.
    - `original_width` number: Ancho en la unidad original.
    - `width_unit` 'cm' | 'm' | 'in' | 'ft': Unidad del ancho original.
    - `original_height` number: Alto en la unidad original.
    - `height_unit` 'cm' | 'm' | 'in' | 'ft': Unidad del alto original.
    - `grams` integer: Peso en gramos (normalizado). Opcional si se envía original_weight + weight_unit.
    - `original_weight` number: Peso en la unidad original. Opcional si se envía grams.
    - `weight_unit` 'g' | 'kg' | 'lbs' | 'oz': Unidad del peso original. Requerido si se envía original_weight.
    - `un_code` string: Código UN de mercancía peligrosa.
    - `classification` string: Clasificación del paquete.
    - `is_flammable` boolean: Si el paquete es inflamable.
    - `is_corrosive` boolean: Si el paquete es corrosivo.
    - `is_fragile` boolean: Si el paquete es frágil.
    - `temperature_min` number: Temperatura mínima de transporte en °C (normalizado).
    - `temperature_max` number: Temperatura máxima de transporte en °C (normalizado).
    - `original_temperature_min` number: Temperatura mínima en la unidad original.
    - `temperature_min_unit` '°C' | '°F': Unidad de temperatura mínima original.
    - `original_temperature_max` number: Temperatura máxima en la unidad original.
    - `temperature_max_unit` '°C' | '°F': Unidad de temperatura máxima original.

## Response `201`

Workflow creado

- object
  - `success` boolean
  - `workflow` Workflow: Workflow que agrupa las tareas de un envío o proceso logístico
    - `id` integer: Identificador del workflow.
    - `external_reference` string, nullable: Referencia externa del workflow.
    - `current_status` string: Estado actual del workflow.
    - `blueprint` object, nullable: Blueprint que define la estructura del workflow. Puede ser null si el blueprint fue eliminado.
      - `id` integer
      - `code` string
      - `steps` object[], nullable: Pasos del blueprint. Solo presente en respuestas de resumen (WorkflowSummaryResource).
        - `id` integer
        - `name` string
    - `data` object, nullable: Datos adicionales asociados al workflow (estructura variable según el blueprint).
    - `tasks` union: Tareas del workflow. Con include_tasks=1 retorna objetos `Task` completos; sin ese parámetro retorna resúmenes `TaskSummary` (subset reducido).
      - Task[]
        - `id` string: Identificador de la tarea.
        - `internal_id` integer: ID interno de la tarea.
        - `grouping_hash` string: Hash que agrupa tareas relacionadas del mismo workflow.
        - `client_code` string, nullable: Código de cliente asociado a la tarea.
        - `carrier` object: Carrier (organización transportista) propietaria de la tarea.
          - `id` integer
          - `subdomain` string
          - `name` string
        - `step` object, nullable: Paso del workflow al que pertenece la tarea.
          - `name` string, nullable
          - `display_name` string, nullable
          - `complete_actions` object[]
          - `fail_actions` object[]
          - `cancel_actions` object[]
        - `is_pickup` boolean: Si la tarea es de pickup (retiro).
        - `status` object: Estado actual de la tarea
          - `id` integer
          - `code` string
          - `name` string
          - `color` string, nullable
          - `metadata` object, nullable
        - `address` Address: Dirección completa como aparece en la respuesta
          - `id` string
          - `name` string
          - `street` string
          - `street_number` string
          - `floor` string, nullable
          - `apartment` string, nullable
          - `reference` string, nullable
          - `zipcode` string, nullable
          - `phone` string, nullable
          - `email` string, nullable
          - `city` object, nullable
            - `id` integer
            - `name` string
          - `state` object, nullable
            - `id` integer
            - `name` string
          - `country` object, nullable
            - `id` integer
            - `name` string
            - `iso` string
          - `geo_latitude` number, float, nullable
          - `geo_longitude` number, float, nullable
        - `recipient_name` string, nullable: Nombre del destinatario.
        - `notes` string, nullable: Notas de la tarea.
        - `is_self_assignable` boolean: Si la tarea puede ser autoasignada.
        - `assigned_to_user` object, nullable: Usuario asignado a la tarea
          - `id` integer
          - `firstname` string
          - `lastname` string
        - `should_complete_after` string, date-time, nullable: Fecha y hora mínima de completado.
        - `should_complete_before` string, date-time, nullable: Fecha y hora máxima de completado.
        - `depends_on_task_ids` string[]: IDs de las tareas de las que depende esta tarea.
        - `cost` number, nullable: Costo asociado a la tarea.
        - `service_time_seconds` integer: Tiempo de servicio en segundos.
        - `requirements_start` Requirement[]: Requisitos para iniciar la tarea.
          - `type` string: Tipo de requisito.
          - `label` string: Etiqueta del requisito.
          - `required` boolean: Si el requisito es obligatorio.
          - `value` union: Valor del requisito (puede ser string, número, booleano o null).
            - string
            - number
            - boolean
        - `requirements_complete` Requirement[]: Requisitos para completar la tarea.
          - `type` string: Tipo de requisito.
          - `label` string: Etiqueta del requisito.
          - `required` boolean: Si el requisito es obligatorio.
          - `value` union: Valor del requisito (puede ser string, número, booleano o null).
            - string
            - number
            - boolean
        - `requirements_fail` Requirement[]: Requisitos para fallar la tarea.
          - `type` string: Tipo de requisito.
          - `label` string: Etiqueta del requisito.
          - `required` boolean: Si el requisito es obligatorio.
          - `value` union: Valor del requisito (puede ser string, número, booleano o null).
            - string
            - number
            - boolean
        - `time_windows` TimeWindow[]: Ventanas de tiempo de la tarea.
          - `from` string, date-time: Inicio de la ventana de tiempo.
          - `to` string, date-time: Fin de la ventana de tiempo.
        - `packages` Package[]
          - `id` integer
          - `label_code` string
          - `external_reference` string, nullable
          - `weight` object: Peso del paquete
            - `value` integer: Peso normalizado en gramos.
            - `original_value` number, nullable: Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).
            - `unit` string: Unidad original (g, kg, lbs, oz).
          - `grams` integer: Peso normalizado en gramos (deprecated, usar weight.value).
          - `length` object: Largo del paquete
            - `value` number: Largo normalizado en centímetros.
            - `original_value` number, nullable
            - `unit` string
          - `width` object: Ancho del paquete
            - `value` number: Ancho normalizado en centímetros.
            - `original_value` number, nullable
            - `unit` string
          - `height` object: Alto del paquete
            - `value` number: Alto normalizado en centímetros.
            - `original_value` number, nullable
            - `unit` string
          - `temperature_min` object, nullable: Temperatura mínima de transporte
            - `value` number: Temperatura normalizada en °C.
            - `original_value` number, nullable
            - `unit` string
          - `temperature_max` object, nullable: Temperatura máxima de transporte
            - `value` number: Temperatura normalizada en °C.
            - `original_value` number, nullable
            - `unit` string
          - `is_flammable` boolean
          - `is_corrosive` boolean
          - `is_fragile` boolean
          - `classification` string, nullable
          - `un_code` string, nullable
        - `shipment` object, nullable: Envío asociado a la tarea
          - `id` integer
          - `ulid` string, nullable
          - `reference` string, nullable
          - `client_code` string, nullable
          - `external_reference` string, nullable
          - `declared_value` number, nullable
          - `control_number` string, nullable
        - `workflow` object, nullable: Workflow al que pertenece la tarea
          - `id` integer
          - `external_reference` string, nullable
          - `step_in_workflow` string, nullable
          - `blueprint` object
            - `type` string
        - `merchant` Merchant: Comercio asociado a una tarea o envío
          - `id` integer
          - `name` string
          - `code` string, nullable
        - `merchant_id` integer, nullable: ID del comercio asociado.
        - `groupable_by_merchant` boolean: Si la tarea puede agruparse por comercio.
        - `created_at` string, date-time
        - `updated_at` string, date-time
      - TaskSummary[]
        - `id` string: ULID de la tarea.
        - `internal_id` integer: ID numérico interno de la tarea.
        - `carrier` object
          - `id` integer
        - `shipment` object, nullable
          - `id` integer
          - `reference` string, nullable
        - `workflow` object, nullable
          - `id` integer
          - `reference` string, nullable
          - `type` string, nullable
          - `step_in_workflow` string, nullable
        - `step` object, nullable
          - `name` string, nullable
          - `display_name` string, nullable
        - `is_pickup` boolean: Si la tarea es de tipo pickup.
        - `status` object
          - `id` integer
          - `code` string

## Other responses

- `401`: No autenticado
- `403`: Sin permisos
- `422`: Error de validación

---

[API](https://skmtc.dev/zipnova/apis/zipnova-rutas-api-organizacional.md) - [All operations](https://skmtc.dev/zipnova/apis/zipnova-rutas-api-organizacional/llms.txt) - [OpenAPI document](https://skmtc.dev/zipnova/apis/zipnova-rutas-api-organizacional/revisions/d57b2ae4ce92?raw)