> 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

## Create quotes

> Get quotes for a shipment based on origin, destination, and packages. If organization is a carrier, shipper\_id is required. If organization is a shipper, carrier\_id is required.

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"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"}}},"Quote":{"type":"object","properties":{"service_type":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","description":"Service type ID"},"code":{"type":"string","description":"Service type code"},"name":{"type":"string","description":"Service type name"}},"description":"Service type information (can be null if no valid service type found)"},"quote":{"type":"number","format":"float","description":"Quote amount for the service type"}}}}},"paths":{"/shipments/quotes":{"post":{"tags":["Shipments"],"summary":"Create quotes","description":"Get quotes for a shipment based on origin, destination, and packages. If organization is a carrier, shipper_id is required. If organization is a shipper, carrier_id is required.","operationId":"createQuotes","requestBody":{"description":"Shipment quote request object","required":true,"content":{"application/json":{"schema":{"type":"object","required":["origin","destination","packages"],"properties":{"origin":{"$ref":"#/components/schemas/AddressInput","description":"Origin address (required, can be address id, place_id, or full address object)"},"destination":{"$ref":"#/components/schemas/AddressInput","description":"Destination address (required, can be address id, place_id, or full address object)"},"packages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/PackageInput"},"description":"Packages array (required, minimum 1 package)"},"declared_value":{"type":"number","minimum":0,"maximum":999999999999,"description":"Declared value (optional, default: 0)"},"shipper_id":{"type":"integer","description":"Shipper ID (required if organization is carrier, must have active contract)"},"carrier_id":{"type":"integer","description":"Carrier ID (required if organization is shipper, must have active contract)"}}}}}},"responses":{"200":{"description":"Quotes obtained","content":{"application/json":{"schema":{"type":"object","properties":{"quotes":{"type":"array","items":{"$ref":"#/components/schemas/Quote"}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## Create Shipment

> Creates a new shipment. If organization is a carrier, shipper\_id is required. If organization is a shipper, carrier\_id is required.

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"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"}}},"Shipment":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"ulid":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"control_number":{"type":"string","nullable":true},"serviceType":{"type":"object","nullable":true,"description":"Service type associated with the shipment","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"shipper":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}}},"carrier":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}}},"status":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"substatus":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}}},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"type":"object","properties":{"total_packages":{"type":"integer"},"total_grams":{"type":"number","description":"Peso total en gramos"},"total_cm3":{"type":"number","description":"Volumen total en centímetros cúbicos"}}},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"related_shipment_id":{"type":"integer"},"related_type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"label_printed_at":{"type":"string","format":"date-time"},"shipped_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"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ó"}}}}}}},"paths":{"/shipments":{"post":{"tags":["Shipments"],"summary":"Create Shipment","description":"Creates a new shipment. If organization is a carrier, shipper_id is required. If organization is a shipper, carrier_id is required.","operationId":"createShipment","requestBody":{"description":"Shipment object","required":true,"content":{"application/json":{"schema":{"type":"object","required":["origin","destination","packages"],"properties":{"origin":{"$ref":"#/components/schemas/AddressInput","description":"Origin address (required, can be address id, place_id, or full address object)"},"destination":{"$ref":"#/components/schemas/AddressInput","description":"Destination address (required, can be address id, place_id, or full address object)"},"packages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/PackageInput"},"description":"Packages array (required, minimum 1 package)"},"external_reference":{"type":"string","maxLength":50,"pattern":"^[a-zA-Z0-9_-]+$","description":"External reference (optional, alphanumeric with dashes and underscores)"},"control_number":{"type":"string","description":"Control number (optional)"},"declared_value":{"type":"number","minimum":0,"maximum":999999999999,"description":"Declared value (optional, default: 0)"},"declared_value_currency":{"type":"string","description":"Currency code for declared value (optional, must be valid currency for organization)"},"requires_pickup":{"type":"boolean","default":false,"description":"Whether shipment requires pickup (optional, default: false)"},"is_public":{"type":"boolean","default":false,"description":"Whether shipment is public (optional, default: false)"},"shipper_id":{"type":"integer","description":"Shipper ID (required if organization is carrier, must have active contract)"},"carrier_id":{"type":"integer","description":"Carrier ID (required if organization is shipper, must have active contract)"},"service_type_id":{"type":"integer","description":"Service type ID (optional, must exist in service_types table for the carrier)"},"service_type_code":{"type":"string","description":"Service type code (optional, must exist in service_types table for the carrier)"},"merchant":{"type":"object","description":"Merchant information (optional)","properties":{"name":{"type":"string"},"code":{"type":"string"}}},"promised_delivery_at":{"type":"string","format":"date-time","description":"Promised delivery time (optional, must be after now)"}}}}}},"responses":{"201":{"description":"Shipment created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"shipment":{"$ref":"#/components/schemas/Shipment"}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## Get Shipment

> Gets a shipment by ID

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"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":{"Shipment":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"ulid":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"control_number":{"type":"string","nullable":true},"serviceType":{"type":"object","nullable":true,"description":"Service type associated with the shipment","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"shipper":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}}},"carrier":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}}},"status":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"substatus":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}}},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"type":"object","properties":{"total_packages":{"type":"integer"},"total_grams":{"type":"number","description":"Peso total en gramos"},"total_cm3":{"type":"number","description":"Volumen total en centímetros cúbicos"}}},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"related_shipment_id":{"type":"integer"},"related_type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"label_printed_at":{"type":"string","format":"date-time"},"shipped_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"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ó"}}}}}}},"paths":{"/shipments/{shipment}":{"get":{"tags":["Shipments"],"summary":"Get Shipment","description":"Gets a shipment by ID","operationId":"getShipment","parameters":[{"name":"shipment","in":"path","required":true,"description":"Shipment ULID","schema":{"type":"string","format":"ulid"}}],"responses":{"200":{"description":"Shipment retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## Track Shipment

> Gets tracking information for a shipment by ULID

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"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":{"ShipmentTrackingEvent":{"type":"object","properties":{"status":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"substatus":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"occurred_at":{"type":"string","format":"date-time"},"comments":{"type":"string"},"metadata":{"type":"object"}}}}},"paths":{"/shipments/{shipment}/tracking":{"get":{"tags":["Shipments"],"summary":"Track Shipment","description":"Gets tracking information for a shipment by ULID","operationId":"getShipmentTracking","parameters":[{"name":"shipment","in":"path","required":true,"description":"Shipment ULID","schema":{"type":"string","format":"ulid"}}],"responses":{"200":{"description":"Tracking information retrieved","content":{"application/json":{"schema":{"properties":{"tracking":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentTrackingEvent"}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## Bulk Track Shipments

> Gets tracking information for multiple shipments in a single request. Shipments the authenticated user cannot access are silently omitted from the response. Maximum 20 shipments per request.

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"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":{"ShipmentTrackingEvent":{"type":"object","properties":{"status":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"substatus":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"occurred_at":{"type":"string","format":"date-time"},"comments":{"type":"string"},"metadata":{"type":"object"}}}}},"paths":{"/shipments/tracking/bulk":{"post":{"tags":["Shipments"],"summary":"Bulk Track Shipments","description":"Gets tracking information for multiple shipments in a single request. Shipments the authenticated user cannot access are silently omitted from the response. Maximum 20 shipments per request.","operationId":"getBulkShipmentTracking","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shipments"],"properties":{"shipments":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"integer"},"description":"Array of shipment IDs. TODO: will migrate to ulid identifiers."}}}}}},"responses":{"200":{"description":"Bulk tracking information retrieved","content":{"application/json":{"schema":{"properties":{"tracking":{"type":"array","items":{"type":"object","properties":{"shipment_id":{"type":"integer"},"tracking":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentTrackingEvent"}}}}}}}}}},"401":{"description":"Unauthorized"},"422":{"description":"Validation error"}}}}}}
```

## Get Shipment Labels

> Gets labels for a shipment by ULID

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"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"}}},"paths":{"/shipments/{shipment}/documentation/labels":{"get":{"tags":["Shipments"],"summary":"Get Shipment Labels","description":"Gets labels for a shipment by ULID","operationId":"getShipmentLabels","parameters":[{"name":"shipment","in":"path","required":true,"description":"Shipment ULID","schema":{"type":"string","format":"ulid"}},{"name":"format","in":"query","required":true,"description":"Label format (pdf, zpl, png)","schema":{"type":"string","enum":["pdf","zpl","png"]}},{"name":"output","in":"query","required":false,"description":"Output mode (optional). `stream`: returns file stream. `download`: forces download. Default: returns base64 encoded content.","schema":{"type":"string","enum":["stream","download"]}}],"responses":{"200":{"description":"Labels retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Base64 encoded file (default output mode)","format":"binary"},"files":{"type":"array","description":"Array of base64 encoded files (only for png format)","items":{"type":"string","format":"binary"}}}}}}}}}}}}
```

## Get Shipment Attachments

> Gets attachments for a shipment by ULID

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"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":{"AttachmentSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"group":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"size":{"type":"integer","description":"Tamaño en bytes"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/shipments/{shipment}/attachments":{"get":{"tags":["Shipments"],"summary":"Get Shipment Attachments","description":"Gets attachments for a shipment by ULID","operationId":"getShipmentAttachments","parameters":[{"name":"shipment","in":"path","required":true,"description":"Shipment ULID","schema":{"type":"string","format":"ulid"}}],"responses":{"200":{"description":"Attachments retrieved","content":{"application/json":{"schema":{"properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentSummary"}}}}}}}}}}}}
```

## Get Shipment Attachment

> Gets a specific attachment for a shipment by ULID

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"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":{"Attachment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"group":{"type":"string"},"name":{"type":"string"},"mime_type":{"type":"string"},"size":{"type":"integer","description":"Tamaño en bytes"},"created_at":{"type":"string","format":"date-time"},"content":{"type":"string","description":"Base64 encoded file","format":"binary"}}}}},"paths":{"/shipments/{shipment}/attachments/{attachment}":{"get":{"tags":["Shipments"],"summary":"Get Shipment Attachment","description":"Gets a specific attachment for a shipment by ULID","operationId":"getShipmentAttachment","parameters":[{"name":"shipment","in":"path","required":true,"description":"Shipment ULID","schema":{"type":"string","format":"ulid"}},{"name":"attachment","in":"path","required":true,"description":"Attachment ID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Attachment retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attachment"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## Cancel Shipment

> Cancels a shipment by ULID. Automatically cancels all pending sequences and tasks.

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"tags":[{"name":"Shipments","description":"Gestión de envíos"}],"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":{"Shipment":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"ulid":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"control_number":{"type":"string","nullable":true},"serviceType":{"type":"object","nullable":true,"description":"Service type associated with the shipment","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"shipper":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}}},"carrier":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}}},"status":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"substatus":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}}},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"type":"object","properties":{"total_packages":{"type":"integer"},"total_grams":{"type":"number","description":"Peso total en gramos"},"total_cm3":{"type":"number","description":"Volumen total en centímetros cúbicos"}}},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"related_shipment_id":{"type":"integer"},"related_type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"label_printed_at":{"type":"string","format":"date-time"},"shipped_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"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ó"}}}}}}},"paths":{"/shipments/{shipment}/cancel":{"post":{"tags":["Shipments"],"summary":"Cancel Shipment","description":"Cancels a shipment by ULID. Automatically cancels all pending sequences and tasks.","operationId":"cancelShipment","parameters":[{"name":"shipment","in":"path","required":true,"description":"Shipment ULID","schema":{"type":"string","format":"ulid"}}],"responses":{"200":{"description":"Shipment cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"shipment":{"$ref":"#/components/schemas/Shipment"}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}}}}}
```

## The Shipment object

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"components":{"schemas":{"Shipment":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"ulid":{"type":"string","format":"ulid"},"external_reference":{"type":"string"},"control_number":{"type":"string","nullable":true},"serviceType":{"type":"object","nullable":true,"description":"Service type associated with the shipment","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"shipper":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}}},"carrier":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subdomain":{"type":"string"}}},"status":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"substatus":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}}},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"totals":{"type":"object","properties":{"total_packages":{"type":"integer"},"total_grams":{"type":"number","description":"Peso total en gramos"},"total_cm3":{"type":"number","description":"Volumen total en centímetros cúbicos"}}},"declared_value":{"type":"number"},"is_public":{"type":"boolean"},"requires_pickup":{"type":"boolean"},"promised_delivery_at":{"type":"string","format":"date-time","nullable":true},"related_shipment_id":{"type":"integer"},"related_type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"label_printed_at":{"type":"string","format":"date-time"},"shipped_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"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ó"}}}}}}}}
```

## The Package object

```json
{"openapi":"3.0.3","info":{"title":"Zipnova Rutas Org API","version":"1.0.0"},"components":{"schemas":{"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ó"}}}}}}}}
```


---

# 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/envios.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.