> 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/envios/recursos-api/envios/modificar-y-cancelar-envios.md). # Modificar y cancelar envíos Entérate como modificar, cancelar y actualizar estados de tus envíos. ### Modificación de envíos {% hint style="warning" %} Actualmente solo es posible editar el atributo de external\_id, siempre y cuando el envío aun no haya sido despachado. Al hacer la modificación, **se reseteará el estado** del envío a Pendiente de Preparación y habrá que **volver a descargar la documentación** de despacho, si ya se hubiera hecho. {% endhint %} ## Actualizar envío > Actualiza el external\_id de un envío. Solo disponible mientras el envío no haya sido despachado al transportista. El cambio regenera las etiquetas automáticamente. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Shipping API V2","version":"2.0.0"},"tags":[{"name":"Envíos","description":"Gestión de envíos y tracking"}],"servers":[{"url":"https://api.zipnova.com.ar/v2","description":"v2 API - Argentina (AR)"},{"url":"https://api.zipnova.cl/v2","description":"v2 API - Chile (CL)"},{"url":"https://api.zipnova.com.mx/v2","description":"v2 API - México (MX)"}],"security":[{"basicAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","description":"Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña","scheme":"basic"},"bearerAuth":{"type":"http","description":"Token de autenticación Bearer OAuth para API V2","bearerFormat":"OAuth","scheme":"bearer"}}},"paths":{"/shipments/{shipment}":{"put":{"tags":["Envíos"],"summary":"Actualizar envío","description":"Actualiza el external_id de un envío. Solo disponible mientras el envío no haya sido despachado al transportista. El cambio regenera las etiquetas automáticamente.","operationId":"1c4fd8fbdfb125556fad122ffbabc0b1","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["external_id"],"properties":{"external_id":{"description":"Nuevo identificador externo del envío (alfanumérico y guiones, máx. 30 caracteres)","type":"string"}},"type":"object"}}}},"responses":{"200":{"description":"Envío actualizado exitosamente","content":{"application/json":{"schema":{"properties":{"shipment_id":{"type":"integer"},"success":{"type":"boolean"},"result":{"properties":{"external_id":{"description":"El nuevo external_id aplicado","type":"string"}},"type":"object"}},"type":"object"}}}},"400":{"description":"Fallo al regenerar etiquetas"},"403":{"description":"Sin permiso para modificar este envío"},"404":{"description":"Envío no encontrado"},"406":{"description":"El envío no puede ser actualizado en su estado actual"},"422":{"description":"Error de validación o nada que actualizar"}}}}}} ``` ### Cancelación de envíos {% hint style="warning" %} **Solo se puede cancelar envíos que no hayan sido despachados**. \ Cuando se solicite cancelar un envío no despachado su estado pasará a **Anulación Confirmada**. **Si el envío ya fue despachado, se generará una Solicitud de Rescate**. \ Con esa solicitud se notificará al transporte para que no haga la entrega, aunque no siempre se puede garantizar que se cumpla la solicitud. {% endhint %} ## Cancelar envío > Cancela un envío o solicita su rescate si ya fue despachado al transportista. El resultado depende del estado actual: envíos no despachados se cancelan directamente, los despachados generan una solicitud de rescate. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Shipping API V2","version":"2.0.0"},"tags":[{"name":"Envíos","description":"Gestión de envíos y tracking"}],"servers":[{"url":"https://api.zipnova.com.ar/v2","description":"v2 API - Argentina (AR)"},{"url":"https://api.zipnova.cl/v2","description":"v2 API - Chile (CL)"},{"url":"https://api.zipnova.com.mx/v2","description":"v2 API - México (MX)"}],"security":[{"basicAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","description":"Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña","scheme":"basic"},"bearerAuth":{"type":"http","description":"Token de autenticación Bearer OAuth para API V2","bearerFormat":"OAuth","scheme":"bearer"}}},"paths":{"/shipments/{shipment}/cancel":{"post":{"tags":["Envíos"],"summary":"Cancelar envío","description":"Cancela un envío o solicita su rescate si ya fue despachado al transportista. El resultado depende del estado actual: envíos no despachados se cancelan directamente, los despachados generan una solicitud de rescate.","operationId":"b028c401cc0551b8e0de1303497c8af4","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Resultado de la operación de cancelación","content":{"application/json":{"schema":{"properties":{"shipment_id":{"description":"ID del envío","type":"integer"},"success":{"description":"Indica si la operación se realizó correctamente","type":"boolean"},"result":{"description":"canceled: el envío fue cancelado. rescue_requested: se solicitó rescate al transportista","type":"string","enum":["canceled","rescue_requested"],"nullable":true}},"type":"object"}}}},"401":{"description":"No fue posible cancelar ni solicitar rescate del envío en su estado actual"},"403":{"description":"Sin permiso para cancelar este envío"},"404":{"description":"Envío no encontrado"}}}}}} ``` ### Actualizar estados de envíos Si deseas actualizar los estados de tus envíos de flota propia, podrás usar este endpoint. Ten en cuenta que solo podrás definir algunos estados. ## Actualizar estado del envío > Registra un cambio de estado en el envío. Solo disponible para envíos de autogestión (self\_service) o con transportistas habilitados para actualización externa. Los estados permitidos dependen del rol del usuario. El estado not\_delivered requiere un substatus obligatorio. ```json {"openapi":"3.0.0","info":{"title":"Zipnova Shipping API V2","version":"2.0.0"},"tags":[{"name":"Envíos","description":"Gestión de envíos y tracking"}],"servers":[{"url":"https://api.zipnova.com.ar/v2","description":"v2 API - Argentina (AR)"},{"url":"https://api.zipnova.cl/v2","description":"v2 API - Chile (CL)"},{"url":"https://api.zipnova.com.mx/v2","description":"v2 API - México (MX)"}],"security":[{"basicAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","description":"Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña","scheme":"basic"},"bearerAuth":{"type":"http","description":"Token de autenticación Bearer OAuth para API V2","bearerFormat":"OAuth","scheme":"bearer"}},"schemas":{"ShipmentApiResource":{"title":"Envío","properties":{"id":{"description":"ID único del envío","type":"integer"},"external_id":{"description":"Identificador externo del envío (e.g. número de orden del cliente)","type":"string","nullable":true},"delivery_id":{"description":"Número de remito asignado por el transportista","type":"string","nullable":true},"carrier_tracking_id":{"description":"Identificador de seguimiento público del transportista","type":"string","nullable":true},"carrier_tracking_id_alt":{"description":"Identificador de seguimiento alternativo del transportista","type":"string","nullable":true},"created_at":{"description":"Fecha y hora de creación del envío (ISO 8601)","type":"string","format":"date-time"},"last_status_at":{"description":"Fecha y hora en que el envío alcanzó su estado actual (ISO 8601)","type":"string","format":"date-time","nullable":true},"delivered_at":{"description":"Fecha y hora de entrega al destinatario (ISO 8601). Presente solo si fue entregado","type":"string","format":"date-time","nullable":true},"delivery_time":{"description":"Tiempos estimados de entrega","properties":{"estimated_delivery":{"description":"Fecha estimada de entrega al destinatario (ISO 8601)","type":"string","format":"date-time","nullable":true},"dropoff_deadline_at":{"description":"Fecha límite para ingresar el envío al transportista (ISO 8601)","type":"string","format":"date-time","nullable":true},"times":{"description":"Desglose de tiempos en días hábiles. Indicados en formato ISO8601 para duraciones de tiempo.","properties":{"preparation":{"description":"Días de preparación antes de despacho","type":"string"},"crossdocking":{"description":"Días de tránsito por crossdocking","type":"string"},"carrier":{"description":"Días de tránsito del transportista","type":"string"},"total":{"description":"Tiempo total estimado en días hábiles","type":"string"}},"type":"object"}},"type":"object"},"account_id":{"description":"ID de la cuenta propietaria del envío","type":"integer"},"parent_shipment_id":{"description":"ID del envío padre. Presente cuando este envío es una devolución o reenvío","type":"integer","nullable":true},"logistic_type":{"description":"Tipo de logística del envío (e.g. crossdock, carrier_dropoff, xd_dropoff, self_service)","type":"string"},"service_type":{"description":"Código del tipo de servicio (e.g. standard, express, pickup_point)","type":"string"},"carrier":{"description":"Transportista asignado al envío","properties":{"id":{"description":"ID del transportista","type":"integer"},"name":{"description":"Nombre del transportista","type":"string"},"logo":{"description":"URL del logotipo del transportista","type":"string","nullable":true}},"type":"object"},"status":{"description":"Código de estado actual del envío (e.g. new, in_transit, delivered)","type":"string"},"status_name":{"description":"Nombre legible del estado actual","type":"string"},"substatus_code":{"description":"Código del subestado actual del envío, si aplica","type":"string","nullable":true},"substatus_name":{"description":"Nombre legible del subestado actual, si aplica","type":"string","nullable":true},"tracking":{"description":"URL de seguimiento público del envío en la plataforma","type":"string","nullable":true},"tracking_external":{"description":"URL de seguimiento en el sitio web del transportista","type":"string","nullable":true},"return_instructions":{"description":"URL con instrucciones de devolución. Solo presente en envíos de tipo reverse logistics","type":"string","nullable":true},"destination":{"description":"Datos completos del destinatario","properties":{"name":{"description":"Nombre completo del destinatario","type":"string"},"document":{"description":"Documento de identidad del destinatario","type":"string"},"street":{"description":"Calle del destinatario","type":"string","nullable":true},"street_number":{"description":"Número de calle del destinatario","type":"string","nullable":true},"street_extras":{"description":"Piso, departamento u otras indicaciones adicionales","type":"string","nullable":true},"city":{"description":"Ciudad de destino","type":"string"},"state":{"description":"Provincia o estado de destino","type":"string"},"zipcode":{"description":"Código postal de destino","type":"string","nullable":true},"phone":{"description":"Teléfono de contacto del destinatario","type":"string"},"email":{"description":"Email de contacto del destinatario","type":"string","format":"email"},"pickup_point":{"description":"Datos del punto de retiro. Solo presente cuando service_type es pickup_point","properties":{"id":{"description":"ID del punto de retiro","type":"integer"},"name":{"description":"Nombre del punto de retiro","type":"string"},"geolocation":{"properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}},"type":"object"}},"type":"object","nullable":true}},"type":"object"},"origin":{"description":"Datos completos del origen del envío","properties":{"id":{"description":"ID del origen en el catálogo de direcciones (address_book_id)","type":"integer"},"name":{"description":"Nombre del punto de origen","type":"string"},"document":{"description":"Documento de identidad del remitente","type":"string","nullable":true},"street":{"description":"Calle de origen","type":"string"},"street_number":{"description":"Número de calle de origen","type":"string"},"street_extras":{"description":"Información adicional de la dirección de origen","type":"string","nullable":true},"city":{"description":"Ciudad de origen","type":"string"},"state":{"description":"Provincia o estado de origen","type":"string"},"zipcode":{"description":"Código postal de origen","type":"string","nullable":true},"phone":{"description":"Teléfono de contacto del origen","type":"string"},"email":{"description":"Email de contacto del origen","type":"string","format":"email"},"is_dropshipping":{"description":"Indica si el envío parte desde un proveedor de dropshipping","type":"boolean"},"supplier":{"description":"Datos del proveedor dropshipping. Solo presente cuando is_dropshipping es true","properties":{"name":{"description":"Nombre del proveedor","type":"string","nullable":true}},"type":"object","nullable":true}},"type":"object"},"declared_value":{"description":"Valor declarado del contenido del envío en la moneda local","type":"number","format":"float"},"price":{"description":"Costo del envío sin impuestos","type":"number","format":"float"},"price_incl_tax":{"description":"Costo del envío con impuestos incluidos","type":"number","format":"float"},"total_weight":{"description":"Peso total del envío en gramos","type":"integer"},"total_volume":{"description":"Volumen total del envío en centímetros cúbicos (cm³)","type":"integer"},"packages":{"description":"Lista de paquetes del envío","type":"array","items":{"properties":{"id":{"description":"ID del paquete","type":"integer"},"label_code":{"description":"Código de etiqueta del paquete","type":"string","nullable":true},"sku_id":{"description":"ID del SKU si el paquete corresponde a un único SKU","type":"integer","nullable":true},"weight":{"description":"Peso del paquete en gramos","type":"integer"},"height":{"description":"Alto del paquete en centímetros","type":"integer"},"width":{"description":"Ancho del paquete en centímetros","type":"integer"},"length":{"description":"Largo del paquete en centímetros","type":"integer"},"volume":{"description":"Volumen del paquete en cm³","type":"integer"},"description_1":{"description":"Primera línea de descripción del contenido","type":"string"},"description_2":{"description":"Segunda línea de descripción del contenido","type":"string","nullable":true},"description_3":{"description":"Tercera línea de descripción del contenido","type":"string","nullable":true},"classification":{"description":"Clasificación arancelaria del contenido","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"tax_class_code":{"description":"Código de clase impositiva del paquete","type":"string","nullable":true},"label_elements":{"description":"Elementos para renderizar en la etiqueta del paquete (códigos de barra, QR, etc.). El contenido varía según el transportista. Presente solo cuando el envío tiene etiqueta generada.","type":"array","items":{"properties":{"id":{"description":"Identificador del elemento (e.g. zipnova_label_code, carrier_tracking_code, carrier_extra_code)","type":"string"},"type":{"description":"Tipo de elemento gráfico","type":"string","enum":["barcode","qrcode"]},"format":{"description":"Formato del código de barras. Solo presente cuando type es barcode","type":"string","nullable":true},"value":{"description":"Valor a codificar en el elemento gráfico","type":"string"}},"type":"object"},"nullable":true},"container":{"description":"Caja o contenedor predefinido. Solo presente si el paquete usa un contenedor guardado","properties":{"id":{"type":"integer"},"description":{"type":"string"},"outer_width":{"description":"Ancho exterior en cm","type":"integer"},"outer_height":{"description":"Alto exterior en cm","type":"integer"},"outer_length":{"description":"Largo exterior en cm","type":"integer"},"inner_width":{"description":"Ancho interior en cm","type":"integer"},"inner_length":{"description":"Largo interior en cm","type":"integer"},"inner_height":{"description":"Alto interior en cm","type":"integer"},"max_weight":{"description":"Peso máximo soportado en gramos","type":"integer"},"empty_weight":{"description":"Peso vacío del contenedor en gramos","type":"integer"}},"type":"object","nullable":true},"items":{"description":"Ítems individuales dentro del paquete","type":"array","items":{"properties":{"id":{"type":"integer"},"sku":{"description":"Datos del SKU vinculado. Los campos internal_sku, name y barcode solo están presentes si el ítem tiene un SKU registrado","properties":{"sku":{"description":"Código SKU","type":"string","nullable":true},"sku_id":{"description":"ID del SKU","type":"integer","nullable":true},"internal_sku":{"description":"SKU interno","type":"string","nullable":true},"name":{"description":"Nombre del producto","type":"string","nullable":true},"barcode":{"description":"Código de barras","type":"string","nullable":true}},"type":"object"},"description":{"description":"Descripción del ítem","type":"string"},"tax_class_code":{"description":"Código de clase impositiva del ítem","type":"string","nullable":true},"must_keep_vertical":{"description":"Indica si el ítem debe mantenerse vertical durante el transporte","type":"boolean"},"weight":{"description":"Peso en gramos","type":"integer"},"width":{"description":"Ancho en cm","type":"integer"},"length":{"description":"Largo en cm","type":"integer"},"height":{"description":"Alto en cm","type":"integer"},"pos_x":{"description":"Posición X dentro del contenedor (cm)","type":"integer","nullable":true},"pos_y":{"description":"Posición Y dentro del contenedor (cm)","type":"integer","nullable":true},"pos_z":{"description":"Posición Z dentro del contenedor (cm)","type":"integer","nullable":true}},"type":"object"}}},"type":"object"}},"tags":{"description":"Etiquetas asociadas al envío","type":"array","items":{"type":"string"}},"related_shipments":{"description":"Envíos relacionados (padre, devoluciones, reenvíos)","type":"array","items":{"properties":{"type":{"description":"Rol del envío relacionado","type":"string","enum":["parent","child"]},"relationship":{"description":"Tipo de relación entre los envíos","type":"string","enum":["copy","return","reshipped"]},"shipment_id":{"description":"ID del envío relacionado","type":"integer"}},"type":"object"}},"source":{"description":"Fuente u origen de creación del envío (e.g. nombre del canal o integración)","type":"string","nullable":true},"marketplace":{"description":"Marketplace asociado al envío. Presente solo si el envío proviene de un marketplace","properties":{"code":{"description":"Código del marketplace","type":"string"},"name":{"description":"Nombre del marketplace","type":"string"}},"type":"object","nullable":true},"order":{"description":"Pedido del canal de venta asociado al envío. Presente solo si el envío tiene un orden vinculado","properties":{"id":{"description":"ID interno del pedido","type":"integer"},"channel":{"description":"Canal de venta (e.g. meli, tiendanube, shopify, vtex)","type":"string"},"channel_created_at":{"description":"Fecha de creación del pedido en el canal (ISO 8601)","type":"string","format":"date-time"},"channel_relations":{"description":"IDs del pedido en el canal de venta (orden, paquete, envío del canal)","type":"array","items":{"properties":{"type":{"type":"string","enum":["order","pack","shipment"]},"id":{"description":"ID del recurso en el canal"}},"type":"object"},"nullable":true}},"type":"object","nullable":true},"fulfillment_order":{"description":"Orden de fulfillment asociada al envío. Presente solo si el envío está vinculado a un proceso de fulfillment","properties":{"id":{"type":"integer"},"status_id":{"description":"ID del estado de la orden de fulfillment","type":"integer"},"external_id":{"description":"ID externo de la orden de fulfillment","type":"string","nullable":true},"items":{"type":"array","items":{"properties":{"sku_id":{"type":"integer"},"qty":{"description":"Cantidad de unidades","type":"integer"},"lot_numbers":{"description":"Números de lote","type":"array","items":{"type":"string"},"nullable":true},"serial_numbers":{"description":"Números de serie","type":"array","items":{"type":"string"},"nullable":true}},"type":"object"}}},"type":"object","nullable":true},"rescue":{"description":"Solicitud de rescate del envío. Presente solo si se solicitó un rescate, resuelto o no","properties":{"requested_at":{"description":"Fecha y hora de la solicitud (ISO 8601)","type":"string","format":"date-time"}},"type":"object","nullable":true}},"type":"object"}}},"paths":{"/shipments/{shipment}/tracking":{"post":{"tags":["Envíos"],"summary":"Actualizar estado del envío","description":"Registra un cambio de estado en el envío. Solo disponible para envíos de autogestión (self_service) o con transportistas habilitados para actualización externa. Los estados permitidos dependen del rol del usuario. El estado not_delivered requiere un substatus obligatorio.","operationId":"1784d43a51141a01855971b2fdc9fdee","parameters":[{"name":"shipment","in":"path","description":"ID del envío","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["status"],"properties":{"status":{"description":"Código del nuevo estado. Los estados disponibles dependen del rol del usuario autenticado","type":"string"},"substatus":{"description":"Código de subestado. Requerido cuando status es not_delivered","type":"string","nullable":true},"comment":{"description":"Comentario adicional sobre el cambio de estado (máx. 150 caracteres)","type":"string","nullable":true}},"type":"object"}}}},"responses":{"200":{"description":"Estado actualizado exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentApiResource"}}}},"400":{"description":"Estado inválido, no permitido para el usuario o transición no válida desde el estado actual"},"403":{"description":"Sin acceso a este envío"},"404":{"description":"Envío no encontrado"}}}}}} ``` #### Estados admitidos para envíos de Flota Propia
EstadoCódigoSubestados
Listo para Despachoready_to_ship
Anulacion Confirmada cancelled
Despachado de Origenshipped
En Transito a Transportein_transit_to_carrier
Recibido Transportereceived_by_carrier
En Camino

in_transit

Entregadodelivered
No Entregadonot_delivered Se debe indicar alguno de estos subestados: