Devoluciones

Los endpoints de creación de envíos utilizan rate limiting 🔴Alto Ver más sobre límites de requests

Recomendamos completar el atributo source con algo que identifique a tu integración, para que luego los clientes puedan definir reglas personalizadas de cotización utilizando el Motor de Reglas, utilizando el atributo source como criterio de filtrado.

Cotizar un envío de logística inversa

El endpoint de cotización de una devolución nos permite obtener los precios y opciones para realizar la misma.

En cada cotización, se deberá indicar la cuenta, valor declarado del envío y detalle de paquetes e items que se devolverán.

Al hacer el request hay algunas particularidades con respecto a la definición de los paquetes e items que los componen que serán devueltos.

Particularidades en la definición de paquetes a devolver En caso de no indicar el array de packages con los paquetes que contendrá la devolución. El sistema interpreta que se devolverán todos los paquetes del envío con todos sus items definidos. Si el array de paquetes esta definido solo se cotizará la devolución de los paquetes que contenga dicho array.
Particularidades en la definición de items a devolver Para cada paquete que se indique en el array de paquetes se deberá indicar que items se devolverán. En caso de no indicar el array de items con los items que contendrán los paquetes de la devolución. El sistema interpreta que se devolverán todos los items del paquete indicado. Si el array de items esta definido dentro de un paquete solo se cotizará la devolución de los items que contenga dicho array.

Cotizar devolución

post

/shipments/{shipment}/return/quote

Obtiene las opciones disponibles para generar un envío de devolución (logística inversa) a partir de un envío existente.

Por defecto se usan todos los paquetes del envío original. Si se envía packages, sólo se cotizan los paquetes indicados (y opcionalmente un subconjunto de sus ítems).

El origen de la devolución es el domicilio del destinatario del envío original. Puede sobreescribirse con origin_address.

Autorizaciones

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 original

Example: 8842301

Cuerpo

account_idintegerRequerido

ID de la cuenta

Example: 1234

sourcestringRequerido

Identificador de la fuente que genera la cotización. Máximo 150 caracteres.

Example: mi-tienda

declared_valuenumberRequerido

Valor declarado de la devolución (numérico, mínimo 0)

Example: 12500

service_typestringOpcional

Filtra los resultados por código de tipo de servicio de devolución (debe ser un tipo marcado como inverso).

Example: return_origin

logistic_typestringOpcional

Filtra los resultados por tipo logístico.

Example: carrier_dropoff

sort_bystring · enumOpcional

Criterio de ordenamiento de los resultados.

Valores posibles:

avoid_rulesbooleanOpcional

Si es true, omite la aplicación de reglas de negocio de la cuenta.

Example: false

Respuestas

200

Lista de opciones de devolución disponibles con precios y tiempos

application/json

sorted_bystring · enumOpcionalExample: priceValores posibles:

originobjectOpcional

destinationobjectOpcional

packagesobject[]Opcional

errorsstring[] · nullableOpcional

Presente cuando no hay opciones disponibles, con el detalle del motivo

Example: ["No hay resultados disponibles para la combinación de origen, destino y servicio"]

400

Datos inválidos o cuenta inactiva

403

Sin acceso a este envío o a la cuenta

404

Envío no encontrado

422

Error de validación

post/shipments/{shipment}/return/quote

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

{
  "account_id": 1234,
  "source": "mi-tienda",
  "declared_value": 12500,
  "service_type": "return_origin",
  "logistic_type": "carrier_dropoff",
  "sort_by": "price",
  "avoid_rules": false,
  "packages": [
    {
      "id": 99001,
      "items": [
        {
          "id": 77501
        }
      ]
    }
  ],
  "origin_address": {
    "street": "Av. Juan B Justo",
    "street_number": "1234",
    "street_extras": "3° B",
    "city": "Palermo",
    "state": "Capital Federal",
    "zipcode": "1425"
  }
}

{
  "sorted_by": "price",
  "origin": {},
  "destination": {},
  "packages": [
    {}
  ],
  "results": {
    "ANY_ADDITIONAL_PROPERTY": {
      "selectable": true,
      "impediments": null,
      "logistic_type": "xd_dropoff",
      "carrier": {
        "id": 3,
        "name": "Andreani",
        "rating": 4.2,
        "logo": "https://cdn.zipnova.com/carriers/andreani.png"
      },
      "service_type": {
        "id": 1,
        "code": "standard_delivery",
        "name": "Entrega estándar",
        "is_urgent": false
      },
      "delivery_time": {
        "warning": "Dear developer, min and max attributes will be deprecated soon. Use provided estimation date or times",
        "min": 3,
        "max": 5,
        "estimated_delivery": "2024-08-18T23:59:59+00:00",
        "estimation_expires_at": "2024-08-15T23:59:59+00:00",
        "times": {
          "preparation": "P0D",
          "crossdocking": "P1D",
          "carrier": {
            "min": "P3D",
            "max": "P5D"
          },
          "total": {
            "min": "P3D",
            "max": "P5D"
          }
        }
      },
      "amounts": {
        "price_shipment": 320.5,
        "price_insurance": 67.3,
        "price": 387.8,
        "price_incl_tax": 469.24,
        "seller_price": 387.8,
        "seller_price_incl_tax": 469.24
      },
      "rate": {
        "source": "tariff",
        "id": 101,
        "tariff_id": 5
      },
      "tags": [
        "cheapest"
      ],
      "pickup_points": [
        {
          "point_id": 55,
          "description": "Sucursal Palermo",
          "open_hours": "09:00 - 18:00",
          "phone": "+5491198765432",
          "location": {
            "street": "Av. Santa Fe",
            "street_number": "3253",
            "street_extras": null,
            "city": "Buenos Aires",
            "state": "Capital Federal",
            "zipcode": "C1425",
            "geolocation": {
              "lat": -34.5907,
              "lng": -58.4239,
              "distance": 1850
            }
          }
        }
      ],
      "dropoff_points": [
        {
          "name": "Sucursal Centro",
          "default_logistic_type": "carrier_dropoff",
          "address": {
            "street": "Corrientes",
            "street_number": "1500",
            "street_extras": null,
            "city": "Buenos Aires",
            "state": "Capital Federal",
            "geolocation": {
              "lat": -34.6044,
              "lng": -58.383
            }
          }
        }
      ]
    }
  },
  "all_results": [
    {
      "selectable": true,
      "impediments": null,
      "logistic_type": "xd_dropoff",
      "carrier": {
        "id": 3,
        "name": "Andreani",
        "rating": 4.2,
        "logo": "https://cdn.zipnova.com/carriers/andreani.png"
      },
      "service_type": {
        "id": 1,
        "code": "standard_delivery",
        "name": "Entrega estándar",
        "is_urgent": false
      },
      "delivery_time": {
        "warning": "Dear developer, min and max attributes will be deprecated soon. Use provided estimation date or times",
        "min": 3,
        "max": 5,
        "estimated_delivery": "2024-08-18T23:59:59+00:00",
        "estimation_expires_at": "2024-08-15T23:59:59+00:00",
        "times": {
          "preparation": "P0D",
          "crossdocking": "P1D",
          "carrier": {
            "min": "P3D",
            "max": "P5D"
          },
          "total": {
            "min": "P3D",
            "max": "P5D"
          }
        }
      },
      "amounts": {
        "price_shipment": 320.5,
        "price_insurance": 67.3,
        "price": 387.8,
        "price_incl_tax": 469.24,
        "seller_price": 387.8,
        "seller_price_incl_tax": 469.24
      },
      "rate": {
        "source": "tariff",
        "id": 101,
        "tariff_id": 5
      },
      "tags": [
        "cheapest"
      ],
      "pickup_points": [
        {
          "point_id": 55,
          "description": "Sucursal Palermo",
          "open_hours": "09:00 - 18:00",
          "phone": "+5491198765432",
          "location": {
            "street": "Av. Santa Fe",
            "street_number": "3253",
            "street_extras": null,
            "city": "Buenos Aires",
            "state": "Capital Federal",
            "zipcode": "C1425",
            "geolocation": {
              "lat": -34.5907,
              "lng": -58.4239,
              "distance": 1850
            }
          }
        }
      ],
      "dropoff_points": [
        {
          "name": "Sucursal Centro",
          "default_logistic_type": "carrier_dropoff",
          "address": {
            "street": "Corrientes",
            "street_number": "1500",
            "street_extras": null,
            "city": "Buenos Aires",
            "state": "Capital Federal",
            "geolocation": {
              "lat": -34.6044,
              "lng": -58.383
            }
          }
        }
      ]
    }
  ],
  "errors": [
    "No hay resultados disponibles para la combinación de origen, destino y servicio"
  ]
}

Crear envío de logística inversa

El endpoint de creación de una devolución nos permite crear la devolución, indicando todo el detalle del mismo y su contenido.

En cada creación, se deberá indicar la cuenta, valor declarado del envío y detalle de paquetes e items que se devolverán. También se indicará el service_type, logistic_type que deben haber sido obtenidos previamente de una cotización.

Al hacer el request hay algunas particularidades con respecto a la definición de los paquetes e items que los componen que serán devueltos.

Particularidades en la definición de paquetes a devolver En caso de no indicar el array de packages con los paquetes que contendrá la devolución. El sistema interpreta que se devolverán todos los paquetes del envío con todos sus items definidos. Si el array de paquetes esta definido solo se creará la devolución de los paquetes que contenga dicho array.
Particularidades en la definición de items a devolver Para cada paquete que se indique en el array de paquetes se deberá indicar que items se devolverán. En caso de no indicar el array de items con los items que contendrán los paquetes de la devolución. El sistema interpreta que se devolverán todos los items del paquete indicado. Si el array de items esta definido dentro de un paquete solo se creará la devolución de los items que contenga dicho array.

Crear envío de devolución

post

/shipments/{shipment}/return

Crea un nuevo envío de devolución (logística inversa) a partir de un envío existente. El origen del envío de devolución es el domicilio del destinatario original. Si se omiten los paquetes, se devuelven todos los del envío original.

Autorizaciones

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 original del cual se genera la devolución

Example: 1042

Cuerpo

account_idintegerRequerido

ID de la cuenta bajo la cual se crea la devolución

Example: 7

service_typestringRequerido

Código del tipo de servicio de devolución (debe ser un servicio de tipo reverse)

Example: standard_reverse

logistic_typestringOpcional

Tipo de logística para la devolución (e.g. crossdock, carrier_dropoff)

Example: crossdock

carrier_idinteger · nullableOpcional

ID del transportista a usar. Si se omite se selecciona automáticamente

sort_bystring · enum · nullableOpcional

Criterio de selección automática del transportista

Example: priceValores posibles:

declared_valuenumber · floatRequerido

Valor declarado del contenido a devolver en la moneda local

Example: 1500

Respuestas

201

Envío de devolución creado 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

substatus_codestring · nullableOpcional

Código del subestado actual del envío, si aplica

Example: ok

substatus_namestring · nullableOpcional

Nombre legible del subestado actual, si aplica

Example: Ok

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

Datos inválidos, ubicación no reconocida o no se pudo cotizar la devolución

403

Sin permiso para crear devoluciones en esta cuenta

404

Envío original no encontrado

422

Error de validación de los datos enviados

post/shipments/{shipment}/return

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

{
  "account_id": 7,
  "service_type": "standard_reverse",
  "logistic_type": "crossdock",
  "carrier_id": null,
  "sort_by": "price",
  "declared_value": 1500,
  "packages": [
    {
      "id": 2001,
      "items": [
        {
          "id": 3001
        }
      ]
    }
  ],
  "origin_address": {
    "street": "Calle Falsa",
    "street_number": "123",
    "street_extras": null,
    "city": "Rosario",
    "state": "Santa Fe",
    "zipcode": "S2000"
  }
}

{
  "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",
  "substatus_code": "ok",
  "substatus_name": "Ok",
  "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": "+5491112345678",
    "email": "juan@example.com",
    "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": "+5493512345678",
    "email": "deposito@empresa.com",
    "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"
        ]
      }
    ]
  },
  "rescue": {
    "requested_at": "2024-08-16T09:41:03+00:00"
  }
}

AnteriorModificar y cancelar envíos SiguientePuntos de despacho

Última actualización hace 3 meses