Modificar y cancelar envíos

Entérate como modificar, cancelar y actualizar estados de tus envíos.

Modificación de envíos

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.

Actualizar envío

put

https://api.zipnova.com.ar/v2https://api.zipnova.cl/v2https://api.zipnova.com.mx/v2

/shipments/{shipment}

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.

Autorizaciones

basicAuthbearerAuth

AuthorizationstringRequerido

Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña

Parámetros de ruta

shipmentintegerRequerido

ID del envío

Example: 1042

Cuerpo

application/json

external_idstringRequerido

Nuevo identificador externo del envío (alfanumérico y guiones, máx. 30 caracteres)

Example: ORDER-9999

Respuestas

200

Envío actualizado exitosamente

application/json

shipment_idintegerOpcionalExample: 1042

successbooleanOpcionalExample: true

400

Fallo al regenerar etiquetas

403

Sin permiso para modificar este envío

404

Envío no encontrado

406

El envío no puede ser actualizado en su estado actual

422

Error de validación o nada que actualizar

put

/shipments/{shipment}

HTTPcURLJavaScriptPython

PUT /v2/shipments/{shipment} HTTP/1.1
Host: api.zipnova.com.ar
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "external_id": "ORDER-9999"
}

{
  "shipment_id": 1042,
  "success": true,
  "result": {
    "external_id": "ORDER-9999"
  }
}

Cancelación de envíos

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.

Cancelar envío

post

https://api.zipnova.com.ar/v2https://api.zipnova.cl/v2https://api.zipnova.com.mx/v2

/shipments/{shipment}/cancel

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.

Autorizaciones

basicAuthbearerAuth

AuthorizationstringRequerido

Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña

Parámetros de ruta

shipmentintegerRequerido

ID del envío

Example: 1042

Respuestas

200

Resultado de la operación de cancelación

application/json

shipment_idintegerOpcional

ID del envío

Example: 1042

successbooleanOpcional

Indica si la operación se realizó correctamente

Example: true

resultstring · enum · nullableOpcional

canceled: el envío fue cancelado. rescue_requested: se solicitó rescate al transportista

Example: canceledValores posibles:

401

No fue posible cancelar ni solicitar rescate del envío en su estado actual

403

Sin permiso para cancelar este envío

404

Envío no encontrado

post

/shipments/{shipment}/cancel

HTTPcURLJavaScriptPython

POST /v2/shipments/{shipment}/cancel HTTP/1.1
Host: api.zipnova.com.ar
Authorization: Basic username:password
Accept: */*

{
  "shipment_id": 1042,
  "success": true,
  "result": "canceled"
}

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

post

https://api.zipnova.com.ar/v2https://api.zipnova.cl/v2https://api.zipnova.com.mx/v2

/shipments/{shipment}/tracking

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.

Autorizaciones

basicAuthbearerAuth

AuthorizationstringRequerido

Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña

Parámetros de ruta

shipmentintegerRequerido

ID del envío

Example: 1042

Cuerpo

application/json

statusstringRequerido

Código del nuevo estado. Los estados disponibles dependen del rol del usuario autenticado

Example: delivered

substatusstring · nullableOpcional

Código de subestado. Requerido cuando status es not_delivered

commentstring · nullableOpcional

Comentario adicional sobre el cambio de estado (máx. 150 caracteres)

Example: Entregado en mano al destinatario

Respuestas

200

Estado actualizado exitosamente

application/json

idintegerOpcional

ID único del envío

Example: 1042

external_idstring · nullableOpcional

Identificador externo del envío (e.g. número de orden del cliente)

Example: ORDER-9821

delivery_idstring · nullableOpcional

Número de remito asignado por el transportista

Example: R-00012345

carrier_tracking_idstring · nullableOpcional

Identificador de seguimiento público del transportista

Example: TRACKING-ABC123

carrier_tracking_id_altstring · nullableOpcional

Identificador de seguimiento alternativo del transportista

Example: TRACKING-XYZ456

created_atstring · date-timeOpcional

Fecha y hora de creación del envío (ISO 8601)

Example: 2024-08-15T10:30:00+00:00

account_idintegerOpcional

ID de la cuenta propietaria del envío

Example: 7

parent_shipment_idinteger · nullableOpcional

ID del envío padre. Presente cuando este envío es una devolución o reenvío

Example: 1040

logistic_typestringOpcional

Tipo de logística del envío (e.g. crossdock, carrier_dropoff, xd_dropoff, self_service)

Example: crossdock

service_typestringOpcional

Código del tipo de servicio (e.g. standard, express, pickup_point)

Example: standard

statusstringOpcional

Código de estado actual del envío (e.g. new, in_transit, delivered)

Example: in_transit

status_namestringOpcional

Nombre legible del estado actual

Example: En camino

trackingstring · nullableOpcional

URL de seguimiento público del envío en la plataforma

Example: https://app.zipnova.com/tracking/1042

tracking_externalstring · nullableOpcional

URL de seguimiento en el sitio web del transportista

Example: https://carrier.com/track?id=ABC123

return_instructionsstring · nullableOpcional

URL con instrucciones de devolución. Solo presente en envíos de tipo reverse logistics

Example: https://app.zipnova.com/return/abc123xyz

declared_valuenumber · floatOpcional

Valor declarado del contenido del envío en la moneda local

Example: 1500

pricenumber · floatOpcional

Costo del envío sin impuestos

Example: 320.5

price_incl_taxnumber · floatOpcional

Costo del envío con impuestos incluidos

Example: 387.8

total_weightintegerOpcional

Peso total del envío en gramos

Example: 1200

total_volumeintegerOpcional

Volumen total del envío en centímetros cúbicos (cm³)

Example: 8000

tagsstring[]Opcional

Etiquetas asociadas al envío

sourcestring · nullableOpcional

Fuente u origen de creación del envío (e.g. nombre del canal o integración)

Example: shopify

400

Estado inválido, no permitido para el usuario o transición no válida desde el estado actual

403

Sin acceso a este envío

404

Envío no encontrado

post

/shipments/{shipment}/tracking

HTTPcURLJavaScriptPython

POST /v2/shipments/{shipment}/tracking HTTP/1.1
Host: api.zipnova.com.ar
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "status": "delivered",
  "substatus": null,
  "comment": "Entregado en mano al destinatario"
}

{
  "id": 1042,
  "external_id": "ORDER-9821",
  "delivery_id": "R-00012345",
  "carrier_tracking_id": "TRACKING-ABC123",
  "carrier_tracking_id_alt": "TRACKING-XYZ456",
  "created_at": "2024-08-15T10:30:00+00:00",
  "delivery_time": {
    "estimated_delivery": "2024-08-18T23:59:59+00:00",
    "dropoff_deadline_at": "2024-08-16T15:00:00+00:00",
    "times": {
      "preparation": "P2D",
      "crossdocking": "P1D",
      "carrier": "P5D",
      "total": "P8D"
    }
  },
  "account_id": 7,
  "parent_shipment_id": 1040,
  "logistic_type": "crossdock",
  "service_type": "standard",
  "carrier": {
    "id": 3,
    "name": "Andreani",
    "logo": "https://cdn.zipnova.com/carriers/andreani.png"
  },
  "status": "in_transit",
  "status_name": "En camino",
  "tracking": "https://app.zipnova.com/tracking/1042",
  "tracking_external": "https://carrier.com/track?id=ABC123",
  "return_instructions": "https://app.zipnova.com/return/abc123xyz",
  "destination": {
    "name": "Juan Pérez",
    "document": "20-12345678-5",
    "street": "Av. Corrientes",
    "street_number": "1234",
    "street_extras": "Piso 3, Dto B",
    "city": "Buenos Aires",
    "state": "Buenos Aires",
    "zipcode": "C1043",
    "phone": "[phone]",
    "email": "[email protected]",
    "pickup_point": {
      "id": 55,
      "name": "Sucursal Palermo",
      "geolocation": {
        "lat": -34.5907,
        "lng": -58.4239
      }
    }
  },
  "origin": {
    "id": 12,
    "name": "Depósito Central",
    "document": "30-71234567-0",
    "street": "Av. San Martín",
    "street_number": "500",
    "street_extras": null,
    "city": "Córdoba",
    "state": "Córdoba",
    "zipcode": "X5000",
    "phone": "[phone]",
    "email": "[email protected]",
    "is_dropshipping": false,
    "supplier": {
      "name": "Proveedor XYZ"
    }
  },
  "declared_value": 1500,
  "price": 320.5,
  "price_incl_tax": 387.8,
  "total_weight": 1200,
  "total_volume": 8000,
  "packages": [
    {
      "id": 2001,
      "label_code": "LP-00099",
      "sku_id": null,
      "weight": 1200,
      "height": 200,
      "width": 300,
      "length": 400,
      "volume": 24000,
      "description_1": "Ropa deportiva",
      "description_2": null,
      "description_3": null,
      "classification": {
        "id": 1,
        "name": "General"
      },
      "tax_class_code": "IVA21",
      "label_elements": [
        {
          "id": "zipnova_label_code",
          "type": "barcode",
          "format": "code128a",
          "value": "LP-00099"
        }
      ],
      "container": {
        "id": 5,
        "description": "Caja chica",
        "outer_width": 320,
        "outer_height": 220,
        "outer_length": 420,
        "inner_width": 310,
        "inner_length": 410,
        "inner_height": 210,
        "max_weight": 5000,
        "empty_weight": 200
      },
      "items": [
        {
          "id": 3001,
          "sku": {
            "sku": "SKU-001",
            "sku_id": 88,
            "internal_sku": "INT-001",
            "name": "Remera Azul Talle M",
            "barcode": "7791234567890"
          },
          "description": "Remera Azul Talle M",
          "tax_class_code": "IVA21",
          "must_keep_vertical": false,
          "weight": 300,
          "width": 100,
          "length": 150,
          "height": 20,
          "pos_x": 0,
          "pos_y": 0,
          "pos_z": 0
        }
      ]
    }
  ],
  "tags": [],
  "related_shipments": [
    {
      "type": "child",
      "relationship": "return",
      "shipment_id": 1043
    }
  ],
  "source": "shopify",
  "marketplace": {
    "code": "meli",
    "name": "MercadoLibre"
  },
  "order": {
    "id": 500,
    "channel": "meli",
    "channel_created_at": "2024-08-14T08:00:00+00:00",
    "channel_relations": [
      {
        "type": "order",
        "id": "2000009876543210"
      }
    ]
  },
  "fulfillment_order": {
    "id": 200,
    "status_id": 3,
    "external_id": "FO-88991",
    "items": [
      {
        "sku_id": 88,
        "qty": 2,
        "lot_numbers": [
          "text"
        ],
        "serial_numbers": [
          "text"
        ]
      }
    ]
  }
}

Estados admitidos para envíos de Flota Propia

Estado	Código	Subestados
Listo para Despacho	ready_to_ship
Anulacion Confirmada	cancelled
Despachado de Origen	shipped
En Transito a Transporte	in_transit_to_carrier
Recibido Transporte	received_by_carrier
En Camino	in_transit
Entregado	delivered
No Entregado	not_delivered	Se debe indicar alguno de estos subestados: