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

# Envíos

## Obtener cotizaciones de envío

> Calcula las cotizaciones disponibles para un envío según origen, destino y paquetes.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AddressInput":{"description":"Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**:\n\n| Modo | Qué enviar | Comportamiento |\n|------|-----------|----------------|\n| **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"title":"1. Reutilizar dirección existente (id)","description":"Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.","required":["id"],"properties":{"id":{"description":"ID de una dirección existente.","type":"string"}},"type":"object"},"AddressByPlaceInput":{"title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.","required":["place_id"],"properties":{"place_id":{"description":"ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.","type":"string"}},"type":"object"},"AddressNewInput":{"title":"3. Dirección nueva (objeto completo)","description":"Crea una dirección nueva. La ubicación se puede indicar de dos formas:\n- **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** envía `city`, `state` y `country` (código ISO).","required":["name","street","street_number"],"properties":{"name":{"description":"Nombre del destinatario/remitente.","type":"string","maxLength":100},"street":{"description":"Nombre de la calle.","type":"string","maxLength":100},"street_number":{"description":"Altura/número.","type":"string","maxLength":10},"floor":{"description":"Piso (opcional).","type":"string","maxLength":5,"nullable":true},"apartment":{"description":"Departamento (opcional).","type":"string","maxLength":10,"nullable":true},"reference":{"description":"Referencia adicional (opcional).","type":"string","maxLength":255,"nullable":true},"city_id":{"description":"ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.","type":"integer"},"city":{"description":"Nombre de la ciudad. Obligatorio si no se envía `city_id`.","type":"string"},"state_id":{"description":"ID interno de la provincia/estado (opcional).","type":"integer"},"state":{"description":"Nombre de la provincia/estado.","type":"string"},"country_id":{"description":"ID interno del país (opcional).","type":"integer"},"country":{"description":"Código ISO del país (ej: AR, MX, CL).","type":"string"},"zipcode":{"description":"Código postal (opcional).","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164 (opcional).","type":"string","nullable":true},"email":{"description":"Email de contacto (opcional).","type":"string","format":"email","nullable":true},"document_type":{"description":"Código del tipo de documento (opcional).","type":"string","nullable":true},"document_number":{"description":"Número de documento (obligatorio si se envía `document_type`).","type":"string","nullable":true},"geo_latitude":{"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":90,"minimum":-90,"nullable":true},"geo_longitude":{"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":180,"minimum":-180,"nullable":true}},"type":"object"},"PackageInput":{"description":"Paquete a incluir en el envío o tarea. Cada medida (peso y dimensiones) se puede enviar de dos formas:\n- **Valor normalizado:** `grams` (gramos), `length`/`width`/`height` (centímetros). El sistema lo guarda tal cual.\n- **Valor con unidad:** `original_weight` + `weight_unit` (y los `original_*` + `*_unit` para dimensiones). El sistema normaliza automáticamente y conserva el valor original.\n\n**Si se envía `id`:** se reutiliza un paquete existente y los demás campos no son necesarios.\n\n**Si no se envía `id`:** `length`, `width` y `height` son obligatorios. El peso debe enviarse como `grams` **o** `original_weight` + `weight_unit`.\n\nUnidades soportadas:\n- Peso: `g`, `kg`, `lbs`, `oz`\n- Dimensiones: `cm`, `m`, `in`, `ft`\n- Temperatura: `°C`, `°F`","properties":{"id":{"description":"ID del paquete existente. Si se envía, los demás campos no son necesarios.","type":"integer"},"external_reference":{"description":"Referencia externa (opcional).","type":"string","maxLength":50,"nullable":true},"description":{"description":"Descripción del paquete (opcional).","type":"string","maxLength":190,"nullable":true},"label_code":{"description":"Código de etiqueta del paquete.","type":"string","maxLength":20},"length":{"description":"Largo en centímetros (normalizado).","type":"integer"},"width":{"description":"Ancho en centímetros (normalizado).","type":"integer"},"height":{"description":"Alto en centímetros (normalizado).","type":"integer"},"original_length":{"description":"Largo en la unidad original.","type":"number"},"length_unit":{"description":"Unidad del largo original.","type":"string","enum":["cm","m","in","ft"]},"original_width":{"description":"Ancho en la unidad original.","type":"number"},"width_unit":{"description":"Unidad del ancho original.","type":"string","enum":["cm","m","in","ft"]},"original_height":{"description":"Alto en la unidad original.","type":"number"},"height_unit":{"description":"Unidad del alto original.","type":"string","enum":["cm","m","in","ft"]},"grams":{"description":"Peso en gramos (normalizado). Opcional si se envía original_weight + weight_unit.","type":"integer"},"original_weight":{"description":"Peso en la unidad original. Opcional si se envía grams.","type":"number"},"weight_unit":{"description":"Unidad del peso original. Requerido si se envía original_weight.","type":"string","enum":["g","kg","lbs","oz"]},"un_code":{"description":"Código UN de mercancía peligrosa.","type":"string"},"classification":{"description":"Clasificación del paquete.","type":"string"},"is_flammable":{"description":"Si el paquete es inflamable.","type":"boolean","default":false},"is_corrosive":{"description":"Si el paquete es corrosivo.","type":"boolean","default":false},"is_fragile":{"description":"Si el paquete es frágil.","type":"boolean","default":false},"temperature_min":{"description":"Temperatura mínima de transporte en °C (normalizado).","type":"number"},"temperature_max":{"description":"Temperatura máxima de transporte en °C (normalizado).","type":"number"},"original_temperature_min":{"description":"Temperatura mínima en la unidad original.","type":"number"},"temperature_min_unit":{"description":"Unidad de temperatura mínima original.","type":"string","enum":["°C","°F"]},"original_temperature_max":{"description":"Temperatura máxima en la unidad original.","type":"number"},"temperature_max_unit":{"description":"Unidad de temperatura máxima original.","type":"string","enum":["°C","°F"]}},"type":"object"},"Quote":{"description":"Cotización de envío","properties":{"service_type_id":{"type":"integer"},"service_type_name":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"estimated_delivery_days":{"type":"integer","nullable":true}},"type":"object"}}},"paths":{"/shipments/quotes":{"post":{"tags":["Shipments"],"summary":"Obtener cotizaciones de envío","description":"Calcula las cotizaciones disponibles para un envío según origen, destino y paquetes.","operationId":"createShipmentQuotes","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["origin","destination","packages"],"properties":{"origin":{"$ref":"#/components/schemas/AddressInput"},"destination":{"$ref":"#/components/schemas/AddressInput"},"packages":{"description":"Paquetes a cotizar.","type":"array","items":{"$ref":"#/components/schemas/PackageInput"},"minItems":1},"declared_value":{"description":"Valor declarado (opcional).","type":"number","minimum":0,"nullable":true},"shipper_id":{"description":"ID del shipper. Requerido si la org es carrier.","type":"string","nullable":true},"carrier_id":{"description":"ID del carrier. Requerido si la org es shipper.","type":"string","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Cotizaciones obtenidas","content":{"application/json":{"schema":{"properties":{"quotes":{"type":"array","items":{"$ref":"#/components/schemas/Quote"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"422":{"description":"Error de validación"}}}}}}
```

## Crear envío

> Crea un nuevo envío. Si la organización es carrier, \`shipper\_id\` es requerido. Si es shipper, \`carrier\_id\` es requerido.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AddressInput":{"description":"Dirección de origen o destino. Se puede enviar de **tres formas mutuamente excluyentes**:\n\n| Modo | Qué enviar | Comportamiento |\n|------|-----------|----------------|\n| **1. Dirección existente** | solo `id` | Reutiliza una dirección ya creada, tal cual está. |\n| **2. Lugar guardado** | solo `place_id` | Copia automáticamente todos los datos desde el lugar. |\n| **3. Dirección nueva** | objeto completo | Crea una dirección nueva. |\n\n**Reglas de exclusión:**\n- `id` y `place_id` son excluyentes entre sí.\n- En el modo 3, la ubicación se indica por IDs internos (`city_id`) **o** por nombres (`city` + `state` + `country`).","oneOf":[{"$ref":"#/components/schemas/AddressByIdInput"},{"$ref":"#/components/schemas/AddressByPlaceInput"},{"$ref":"#/components/schemas/AddressNewInput"}]},"AddressByIdInput":{"title":"1. Reutilizar dirección existente (id)","description":"Reutiliza una dirección ya creada. Se usa exactamente como está; no se modifica ningún campo.","required":["id"],"properties":{"id":{"description":"ID de una dirección existente.","type":"string"}},"type":"object"},"AddressByPlaceInput":{"title":"2. Reutilizar lugar guardado (place_id)","description":"Reutiliza un lugar guardado. Todos los datos se copian automáticamente desde el lugar.","required":["place_id"],"properties":{"place_id":{"description":"ID del lugar guardado (con prefijo `ple_`). Debe existir en la lista de lugares de la organización.","type":"string"}},"type":"object"},"AddressNewInput":{"title":"3. Dirección nueva (objeto completo)","description":"Crea una dirección nueva. La ubicación se puede indicar de dos formas:\n- **Por IDs internos:** envía `city_id` (y opcionalmente `state_id` / `country_id`).\n- **Por nombres:** envía `city`, `state` y `country` (código ISO).","required":["name","street","street_number"],"properties":{"name":{"description":"Nombre del destinatario/remitente.","type":"string","maxLength":100},"street":{"description":"Nombre de la calle.","type":"string","maxLength":100},"street_number":{"description":"Altura/número.","type":"string","maxLength":10},"floor":{"description":"Piso (opcional).","type":"string","maxLength":5,"nullable":true},"apartment":{"description":"Departamento (opcional).","type":"string","maxLength":10,"nullable":true},"reference":{"description":"Referencia adicional (opcional).","type":"string","maxLength":255,"nullable":true},"city_id":{"description":"ID interno de la ciudad. Obligatorio si no se envía `city`, `state` y `country`.","type":"integer"},"city":{"description":"Nombre de la ciudad. Obligatorio si no se envía `city_id`.","type":"string"},"state_id":{"description":"ID interno de la provincia/estado (opcional).","type":"integer"},"state":{"description":"Nombre de la provincia/estado.","type":"string"},"country_id":{"description":"ID interno del país (opcional).","type":"integer"},"country":{"description":"Código ISO del país (ej: AR, MX, CL).","type":"string"},"zipcode":{"description":"Código postal (opcional).","type":"string","nullable":true},"phone":{"description":"Teléfono en formato E.164 (opcional).","type":"string","nullable":true},"email":{"description":"Email de contacto (opcional).","type":"string","format":"email","nullable":true},"document_type":{"description":"Código del tipo de documento (opcional).","type":"string","nullable":true},"document_number":{"description":"Número de documento (obligatorio si se envía `document_type`).","type":"string","nullable":true},"geo_latitude":{"description":"Latitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":90,"minimum":-90,"nullable":true},"geo_longitude":{"description":"Longitud (opcional). Si se omite, se geocodifica desde la dirección.","type":"number","format":"float","maximum":180,"minimum":-180,"nullable":true}},"type":"object"},"PackageInput":{"description":"Paquete a incluir en el envío o tarea. Cada medida (peso y dimensiones) se puede enviar de dos formas:\n- **Valor normalizado:** `grams` (gramos), `length`/`width`/`height` (centímetros). El sistema lo guarda tal cual.\n- **Valor con unidad:** `original_weight` + `weight_unit` (y los `original_*` + `*_unit` para dimensiones). El sistema normaliza automáticamente y conserva el valor original.\n\n**Si se envía `id`:** se reutiliza un paquete existente y los demás campos no son necesarios.\n\n**Si no se envía `id`:** `length`, `width` y `height` son obligatorios. El peso debe enviarse como `grams` **o** `original_weight` + `weight_unit`.\n\nUnidades soportadas:\n- Peso: `g`, `kg`, `lbs`, `oz`\n- Dimensiones: `cm`, `m`, `in`, `ft`\n- Temperatura: `°C`, `°F`","properties":{"id":{"description":"ID del paquete existente. Si se envía, los demás campos no son necesarios.","type":"integer"},"external_reference":{"description":"Referencia externa (opcional).","type":"string","maxLength":50,"nullable":true},"description":{"description":"Descripción del paquete (opcional).","type":"string","maxLength":190,"nullable":true},"label_code":{"description":"Código de etiqueta del paquete.","type":"string","maxLength":20},"length":{"description":"Largo en centímetros (normalizado).","type":"integer"},"width":{"description":"Ancho en centímetros (normalizado).","type":"integer"},"height":{"description":"Alto en centímetros (normalizado).","type":"integer"},"original_length":{"description":"Largo en la unidad original.","type":"number"},"length_unit":{"description":"Unidad del largo original.","type":"string","enum":["cm","m","in","ft"]},"original_width":{"description":"Ancho en la unidad original.","type":"number"},"width_unit":{"description":"Unidad del ancho original.","type":"string","enum":["cm","m","in","ft"]},"original_height":{"description":"Alto en la unidad original.","type":"number"},"height_unit":{"description":"Unidad del alto original.","type":"string","enum":["cm","m","in","ft"]},"grams":{"description":"Peso en gramos (normalizado). Opcional si se envía original_weight + weight_unit.","type":"integer"},"original_weight":{"description":"Peso en la unidad original. Opcional si se envía grams.","type":"number"},"weight_unit":{"description":"Unidad del peso original. Requerido si se envía original_weight.","type":"string","enum":["g","kg","lbs","oz"]},"un_code":{"description":"Código UN de mercancía peligrosa.","type":"string"},"classification":{"description":"Clasificación del paquete.","type":"string"},"is_flammable":{"description":"Si el paquete es inflamable.","type":"boolean","default":false},"is_corrosive":{"description":"Si el paquete es corrosivo.","type":"boolean","default":false},"is_fragile":{"description":"Si el paquete es frágil.","type":"boolean","default":false},"temperature_min":{"description":"Temperatura mínima de transporte en °C (normalizado).","type":"number"},"temperature_max":{"description":"Temperatura máxima de transporte en °C (normalizado).","type":"number"},"original_temperature_min":{"description":"Temperatura mínima en la unidad original.","type":"number"},"temperature_min_unit":{"description":"Unidad de temperatura mínima original.","type":"string","enum":["°C","°F"]},"original_temperature_max":{"description":"Temperatura máxima en la unidad original.","type":"number"},"temperature_max_unit":{"description":"Unidad de temperatura máxima original.","type":"string","enum":["°C","°F"]}},"type":"object"},"Shipment":{"description":"Envío completo con todos sus datos","properties":{"id":{"description":"ID interno del envío.","type":"integer","format":"int64"},"ulid":{"description":"Identificador secundario del envío.","type":"string"},"external_reference":{"description":"Referencia externa del envío.","type":"string","nullable":true},"control_number":{"description":"Número de control del envío.","type":"string","nullable":true},"serviceType":{"description":"Tipo de servicio asociado al envío","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"shipper":{"description":"Organización dadora de carga","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"carrier":{"description":"Organización transportista","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"status":{"description":"Estado actual del envío","properties":{"code":{"type":"string"},"name":{"type":"string"},"color":{"description":"Color hexadecimal del estado.","type":"string","nullable":true},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"properties":{"total_packages":{"type":"integer"},"total_grams":{"description":"Peso total en gramos.","type":"number"},"total_cm3":{"description":"Volumen total en centímetros cúbicos.","type":"number"}},"type":"object"},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"related_shipment_id":{"description":"ID del envío relacionado (ej. retorno o reenvío).","type":"integer","nullable":true},"related_type":{"description":"Tipo de relación con el envío asociado.","type":"string","nullable":true},"finished_at":{"description":"Fecha en que el envío fue finalizado.","type":"string","format":"date-time","nullable":true},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"label_printed_at":{"type":"string","format":"date-time","nullable":true},"shipped_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, lbs, oz).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/shipments":{"post":{"tags":["Shipments"],"summary":"Crear envío","description":"Crea un nuevo envío. Si la organización es carrier, `shipper_id` es requerido. Si es shipper, `carrier_id` es requerido.","operationId":"createShipment","requestBody":{"description":"Datos del envío a crear","required":true,"content":{"application/json":{"schema":{"required":["origin","destination","packages"],"properties":{"origin":{"$ref":"#/components/schemas/AddressInput"},"destination":{"$ref":"#/components/schemas/AddressInput"},"packages":{"description":"Paquetes del envío (mínimo 1).","type":"array","items":{"$ref":"#/components/schemas/PackageInput"},"minItems":1},"external_reference":{"description":"Referencia externa del envío.","type":"string","maxLength":50,"nullable":true},"declared_value":{"description":"Valor declarado del envío.","type":"number","minimum":0,"nullable":true},"declared_value_currency":{"description":"Moneda del valor declarado (debe ser válida para la organización).","type":"string","nullable":true},"requires_pickup":{"description":"Si el envío requiere pickup previo.","type":"boolean","default":false},"is_public":{"description":"Si el tracking del envío es público.","type":"boolean","default":false},"shipper_id":{"description":"ID del shipper. Requerido si la org es carrier.","type":"string"},"carrier_id":{"description":"ID del carrier. Requerido si la org es shipper.","type":"string"},"service_type_id":{"description":"ID del tipo de servicio (opcional).","type":"integer","nullable":true},"service_type_code":{"description":"Código del tipo de servicio (alternativa a service_type_id).","type":"string","nullable":true},"merchant":{"description":"Información del comercio (opcional)","properties":{"name":{"type":"string"},"code":{"type":"string"}},"type":"object","nullable":true},"promised_delivery_at":{"description":"Fecha prometida de entrega.","type":"string","format":"date-time","nullable":true}},"type":"object"}}}},"responses":{"201":{"description":"Envío creado","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"shipment":{"$ref":"#/components/schemas/Shipment"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"422":{"description":"Error de validación"}}}}}}
```

## Obtener envío

> Obtiene los detalles completos de un envío.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Shipment":{"description":"Envío completo con todos sus datos","properties":{"id":{"description":"ID interno del envío.","type":"integer","format":"int64"},"ulid":{"description":"Identificador secundario del envío.","type":"string"},"external_reference":{"description":"Referencia externa del envío.","type":"string","nullable":true},"control_number":{"description":"Número de control del envío.","type":"string","nullable":true},"serviceType":{"description":"Tipo de servicio asociado al envío","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"shipper":{"description":"Organización dadora de carga","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"carrier":{"description":"Organización transportista","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"status":{"description":"Estado actual del envío","properties":{"code":{"type":"string"},"name":{"type":"string"},"color":{"description":"Color hexadecimal del estado.","type":"string","nullable":true},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"properties":{"total_packages":{"type":"integer"},"total_grams":{"description":"Peso total en gramos.","type":"number"},"total_cm3":{"description":"Volumen total en centímetros cúbicos.","type":"number"}},"type":"object"},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"related_shipment_id":{"description":"ID del envío relacionado (ej. retorno o reenvío).","type":"integer","nullable":true},"related_type":{"description":"Tipo de relación con el envío asociado.","type":"string","nullable":true},"finished_at":{"description":"Fecha en que el envío fue finalizado.","type":"string","format":"date-time","nullable":true},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"label_printed_at":{"type":"string","format":"date-time","nullable":true},"shipped_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, lbs, oz).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/shipments/{shipment}":{"get":{"tags":["Shipments"],"summary":"Obtener envío","description":"Obtiene los detalles completos de un envío.","operationId":"getShipment","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Envío obtenido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"}}}}}}
```

## Seguimiento de envío

> Retorna el historial de estados del envío ordenado cronológicamente.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"ShipmentTrackingEvent":{"description":"Evento del historial de seguimiento de un envío","properties":{"status":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object"},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"occurred_at":{"type":"string","format":"date-time"},"comments":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"}}},"paths":{"/shipments/{shipment}/tracking":{"get":{"tags":["Shipments"],"summary":"Seguimiento de envío","description":"Retorna el historial de estados del envío ordenado cronológicamente.","operationId":"getShipmentTracking","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Historial de seguimiento","content":{"application/json":{"schema":{"properties":{"tracking":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentTrackingEvent"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"}}}}}}
```

## Seguimiento masivo de envíos

> Retorna el historial de seguimiento para múltiples envíos en una sola llamada.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"ShipmentTrackingEvent":{"description":"Evento del historial de seguimiento de un envío","properties":{"status":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object"},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true},"occurred_at":{"type":"string","format":"date-time"},"comments":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"type":"object"}}},"paths":{"/shipments/tracking/bulk":{"post":{"tags":["Shipments"],"summary":"Seguimiento masivo de envíos","description":"Retorna el historial de seguimiento para múltiples envíos en una sola llamada.","operationId":"getBulkTracking","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["shipments"],"properties":{"shipments":{"description":"IDs de los envíos a consultar.","type":"array","items":{"type":"integer"}}},"type":"object"}}}},"responses":{"200":{"description":"Seguimiento masivo","content":{"application/json":{"schema":{"properties":{"tracking":{"type":"array","items":{"properties":{"shipment_id":{"type":"integer"},"tracking":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentTrackingEvent"}}},"type":"object"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"422":{"description":"Error de validación"}}}}}}
```

## Obtener etiquetas del envío

> Genera y retorna las etiquetas del envío en formato PDF, PNG o ZPL.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}}},"paths":{"/shipments/{shipment}/documentation/labels":{"get":{"tags":["Shipments"],"summary":"Obtener etiquetas del envío","description":"Genera y retorna las etiquetas del envío en formato PDF, PNG o ZPL.","operationId":"getShipmentLabels","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}},{"name":"format","in":"query","description":"Formato de salida de la etiqueta","required":true,"schema":{"type":"string","enum":["pdf","png","zpl"]}},{"name":"output","in":"query","description":"Modo de salida: `base64` retorna el archivo codificado en base64 (por defecto), `stream` lo retorna como stream, `download` como descarga.","required":false,"schema":{"type":"string","default":"base64","enum":["base64","stream","download"]}}],"responses":{"200":{"description":"Etiquetas generadas. Para output=base64 (por defecto), retorna JSON con las etiquetas codificadas. Para output=stream o download, retorna el archivo binario directamente (no JSON).","content":{"application/json":{"schema":{"description":"Respuesta JSON cuando output=base64 (por defecto).","properties":{"data":{"properties":{"file":{"description":"Etiqueta en base64 (para format=pdf o zpl).","type":"string","format":"byte","nullable":true},"files":{"description":"Etiquetas en base64 (para format=png, una por página).","type":"array","items":{"type":"string","format":"byte"},"nullable":true}},"type":"object"}},"type":"object"}},"application/octet-stream":{"schema":{"description":"Archivo binario cuando output=stream o download.","type":"string","format":"binary"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"},"422":{"description":"Formato inválido"}}}}}}
```

## Listar adjuntos del envío

> Retorna la lista de archivos adjuntos de todas las tareas del envío.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"AttachmentSummary":{"description":"Resumen de un adjunto sin contenido","properties":{"id":{"type":"string","format":"uuid"},"group":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"size":{"description":"Tamaño en bytes.","type":"integer"},"created_at":{"type":"string","format":"date-time"}},"type":"object"}}},"paths":{"/shipments/{shipment}/attachments":{"get":{"tags":["Shipments"],"summary":"Listar adjuntos del envío","description":"Retorna la lista de archivos adjuntos de todas las tareas del envío.","operationId":"getShipmentAttachments","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista de adjuntos","content":{"application/json":{"schema":{"properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentSummary"}}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"}}}}}}
```

## Obtener adjunto del envío

> Retorna el contenido de un adjunto específico del envío, codificado en base64.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Attachment":{"description":"Adjunto con contenido en base64","properties":{"id":{"type":"string","format":"uuid"},"group":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"size":{"description":"Tamaño en bytes.","type":"integer"},"created_at":{"type":"string","format":"date-time"},"content":{"description":"Contenido del archivo codificado en base64.","type":"string","format":"byte"}},"type":"object"}}},"paths":{"/shipments/{shipment}/attachments/{attachment}":{"get":{"tags":["Shipments"],"summary":"Obtener adjunto del envío","description":"Retorna el contenido de un adjunto específico del envío, codificado en base64.","operationId":"getShipmentAttachment","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}},{"name":"attachment","in":"path","description":"UUID del adjunto","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Adjunto obtenido con contenido en base64","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attachment"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Adjunto no encontrado"}}}}}}
```

## Cancelar envío

> Cancela un envío. Cancela automáticamente todas las tareas y workflows pendientes asociados.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"servers":[{"url":"https://{subdomain}.routes.zipnova.app/api/v1","description":"API organizacional de Zipnova Rutas","variables":{"subdomain":{"default":"mi-organizacion","description":"Subdominio de la organización (ej: mi-empresa, logistica-sur)"}}}],"security":[{"orgToken":[]}],"components":{"securitySchemes":{"orgToken":{"type":"http","description":"Token Bearer generado en la sección de integraciones de tu organización en Zipnova Rutas.","bearerFormat":"API Token","scheme":"bearer"}},"schemas":{"Shipment":{"description":"Envío completo con todos sus datos","properties":{"id":{"description":"ID interno del envío.","type":"integer","format":"int64"},"ulid":{"description":"Identificador secundario del envío.","type":"string"},"external_reference":{"description":"Referencia externa del envío.","type":"string","nullable":true},"control_number":{"description":"Número de control del envío.","type":"string","nullable":true},"serviceType":{"description":"Tipo de servicio asociado al envío","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"shipper":{"description":"Organización dadora de carga","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"carrier":{"description":"Organización transportista","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"status":{"description":"Estado actual del envío","properties":{"code":{"type":"string"},"name":{"type":"string"},"color":{"description":"Color hexadecimal del estado.","type":"string","nullable":true},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"properties":{"total_packages":{"type":"integer"},"total_grams":{"description":"Peso total en gramos.","type":"number"},"total_cm3":{"description":"Volumen total en centímetros cúbicos.","type":"number"}},"type":"object"},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"related_shipment_id":{"description":"ID del envío relacionado (ej. retorno o reenvío).","type":"integer","nullable":true},"related_type":{"description":"Tipo de relación con el envío asociado.","type":"string","nullable":true},"finished_at":{"description":"Fecha en que el envío fue finalizado.","type":"string","format":"date-time","nullable":true},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"label_printed_at":{"type":"string","format":"date-time","nullable":true},"shipped_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, lbs, oz).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true}},"type":"object"}}},"paths":{"/shipments/{shipment}/cancel":{"post":{"tags":["Shipments"],"summary":"Cancelar envío","description":"Cancela un envío. Cancela automáticamente todas las tareas y workflows pendientes asociados.","operationId":"cancelShipment","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Envío cancelado","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"shipment":{"$ref":"#/components/schemas/Shipment"}},"type":"object"}}}},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"404":{"description":"Envío no encontrado"},"422":{"description":"El envío no puede cancelarse en su estado actual"}}}}}}
```

## The Shipment object

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Shipment":{"description":"Envío completo con todos sus datos","properties":{"id":{"description":"ID interno del envío.","type":"integer","format":"int64"},"ulid":{"description":"Identificador secundario del envío.","type":"string"},"external_reference":{"description":"Referencia externa del envío.","type":"string","nullable":true},"control_number":{"description":"Número de control del envío.","type":"string","nullable":true},"serviceType":{"description":"Tipo de servicio asociado al envío","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"shipper":{"description":"Organización dadora de carga","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"carrier":{"description":"Organización transportista","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"},"status":{"description":"Estado actual del envío","properties":{"code":{"type":"string"},"name":{"type":"string"},"color":{"description":"Color hexadecimal del estado.","type":"string","nullable":true},"substatus":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object","nullable":true}},"type":"object"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"properties":{"total_packages":{"type":"integer"},"total_grams":{"description":"Peso total en gramos.","type":"number"},"total_cm3":{"description":"Volumen total en centímetros cúbicos.","type":"number"}},"type":"object"},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"related_shipment_id":{"description":"ID del envío relacionado (ej. retorno o reenvío).","type":"integer","nullable":true},"related_type":{"description":"Tipo de relación con el envío asociado.","type":"string","nullable":true},"finished_at":{"description":"Fecha en que el envío fue finalizado.","type":"string","format":"date-time","nullable":true},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"label_printed_at":{"type":"string","format":"date-time","nullable":true},"shipped_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"Address":{"description":"Dirección completa como aparece en la respuesta","properties":{"id":{"type":"string"},"name":{"type":"string"},"street":{"type":"string"},"street_number":{"type":"string"},"floor":{"type":"string","nullable":true},"apartment":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"city":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"state":{"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object","nullable":true},"country":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"iso":{"type":"string"}},"type":"object","nullable":true},"geo_latitude":{"type":"number","format":"float","nullable":true},"geo_longitude":{"type":"number","format":"float","nullable":true}},"type":"object"},"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, lbs, oz).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true}},"type":"object"}}}}
```

## The Package object

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Rutas API Organizacional","version":"1.0.0"},"components":{"schemas":{"Package":{"description":"Paquete en la respuesta con información completa de medidas.\n\n**Importante:** Todos los campos de medida son objetos que contienen:\n- `value`: valor **normalizado** en la unidad interna del sistema (g para peso, cm para dimensiones, °C para temperatura).\n- `original_value`: el valor **tal cual lo ingresó el usuario**. Es `null` si el usuario envió directamente el valor normalizado.\n- `unit`: la unidad original que usó el usuario; si no especificó ninguna, se devuelve la unidad por defecto del sistema.","properties":{"id":{"type":"integer","format":"int64"},"label_code":{"type":"string"},"external_reference":{"type":"string","nullable":true},"weight":{"description":"Peso del paquete","properties":{"value":{"description":"Peso normalizado en gramos.","type":"integer"},"original_value":{"description":"Peso tal cual lo ingresó el usuario (null si solo envió el valor normalizado).","type":"number","nullable":true},"unit":{"description":"Unidad original (g, kg, lbs, oz).","type":"string"}},"type":"object"},"grams":{"description":"Peso normalizado en gramos (deprecated, usar weight.value).","type":"integer"},"length":{"description":"Largo del paquete","properties":{"value":{"description":"Largo normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"width":{"description":"Ancho del paquete","properties":{"value":{"description":"Ancho normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"height":{"description":"Alto del paquete","properties":{"value":{"description":"Alto normalizado en centímetros.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object"},"temperature_min":{"description":"Temperatura mínima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"temperature_max":{"description":"Temperatura máxima de transporte","properties":{"value":{"description":"Temperatura normalizada en °C.","type":"number"},"original_value":{"type":"number","nullable":true},"unit":{"type":"string"}},"type":"object","nullable":true},"is_flammable":{"type":"boolean"},"is_corrosive":{"type":"boolean"},"is_fragile":{"type":"boolean"},"classification":{"type":"string","nullable":true},"un_code":{"type":"string","nullable":true}},"type":"object"}}}}
```