---
title: "Crear tarea"
method: POST
path: "/tasks"
tags: ["Tasks"]
---

# Crear tarea

`POST /tasks`

## Request

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

Crea una nueva tarea independiente (no asociada a un workflow).

## Request body

- object
  - `address` union, required: 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.
  - `packages` PackageInput[], required: Paquetes de la tarea.
    - `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.
  - `external_reference` string, nullable: Referencia externa de la tarea.
  - `recipient_name` string, nullable: Nombre del destinatario.
  - `notes` string, nullable: Notas adicionales para el conductor.
  - `requirements_start` Requirement[], nullable: 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[], nullable: 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[], nullable: 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[], nullable: Ventanas de tiempo.
    - `from` string, date-time: Inicio de la ventana de tiempo.
    - `to` string, date-time: Fin de la ventana de tiempo.

## Response `201`

Tarea creada

- object
  - `success` boolean
  - `task` Task: Tarea de entrega o pickup
    - `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

## 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)