Crear Envíos

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

Al crear un envío necesitarás informar algunos datos que surgen de la cotización.

Luego de cotizar, debes almacenar los valores de logistic_type, service_type, carrier_id de la opción de envío deseada, para luego utilizarlos al crear el envío.

Si se trata de un envío a retirar por sucursal, también debes almacenar el point_id de la ubicación donde se vaya a hacer el retiro del envío por el destinatario.

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.

Crear envíos indicando items a despachar

Permite crear un envío indicando un conjunto de productos a despachar. La API empaquetará los items en paquetes de acuerdo a la lógica definida en la cuenta, y teniendo en cuenta los contenedores configurados.

Crear envío (basado en items) - Recomendado

POST /v2/shipments

Este request te permitirá crear envíos indicando los articulos que son parte del despacho. El sistema los agrupará en paquetes automáticamente, según las reglas definidas en la cuenta.

Request Body

Name	Type	Description
account_id*	int	ID de la cuenta
origin_id*	int	ID del origen del envío
logistic_type	string	Código de la forma de despacho del envío. Ejemplo: carrier_dropoff Se recomienda explicitarlo basado en los resultados obtenidos en la cotización utilizar la opcion de envio deseada
service_type	string	Código de la forma de entrega del envío. Ejemplo: standard_delivery Se recomienda explicitarlo basado en los resultados obtenidos en la cotización utilizar la opcion de envio deseada
carrier_id	int	ID del transporte que hará la entrega. Se recomienda explicitarlo basado en los resultados obtenidos en la cotización.
source	string (150)	Utilizado en algunas integraciones para identificar el canal de venta.
declared_value*	float	Valor declarado del envío. Monto que se asegurará. Para no utilizar seguro se debe enviar en cero.
destination.name*	string (100)	Nombre y apellido del destinatario
destination.street*	string (100)	Calle del domicilio de entrega. Requerido solo en entregas a domicilio.
destination.street_number*	string (10)	Altura/nro de puerta del domicilio de entrega. Requerido solo en entregas a domicilio.
destination.street_extras	string (190)	Referencias adicionales del domicilio como piso, departamento, nro de lote, etc. Requerido solo en entregas a domicilio.
destination.point_id	int	ID de la ubicación de entrega. Requerido solo cuando la entrega es en un punto de entrega.
destination.document*	string (50)	Número de documento (DNI, RUT, o lo que corresponda) del destinatario
destination.email*	email (150)	Dirección de correo electrónico del destinatario
destination.phone*	string (50)	Número de contacto del destinatario
destination.state*	string	Nombre del Estado del domicilio del destinatario. AR: provincia CL: región MX: estado Requerido solo en entregas a domicilio.
destination.city*	string	Nombre de la ciudad del domicilio del destinatario. AR: localidad CL: comuna MX: ciudad Requerido solo en entregas a domicilio.
destination.zipcode*	string	Codigo postal de la dirección de destino. Requerido solo en entregas a domicilio. Dato no requerido en Chile.
destination.country	string	Código ISO 3166-1 alfa-2 del país Argentina: AR Chile: CL México: MX
destination*	object	Objeto con datos del destinatario
items*	array[Item]	Array de objetos Item. Cada Item es un articulo a enviar. El máximo de artículos por envío es 1000. Ten en cuenta que más allá de la cantidad de items, un envío no puede resultar en más de 99 paquetes.
items.*.sku	string (190)	Se intentará vincular a un producto cargado en el catálogo de Zippin.
items.*.weight*	int	Peso en gramos.
items.*.classification_id	int	ID de clasificación de producto. Si se omite se utilizará la clasificación General (1). Ver clasificaciones disponibles.
items.*.height*	int	Alto del artículo, en centímetros.
items.*.width*	int	Ancho del artículo, en centímetros.
items.*.length*	int	Largo del artículo, en centímetros.
items.*.description	string (190)	Descripción o nombre del artículo
external_id*	string (30)	ID del envío en tus sistemas. Es para tu propia referencia.
type_packaging	string	Indica la forma de empaquetar los productos. Si se omite se usa el que tenga definido la cuenta por default. Valores posible: dynamic: empaquetado dinámico boxes: usar cajas configuradas en la cuenta none: no empaquetar (cada item debe resultar en un package separado)

201: Created El envío se crea correctamente.

{
    // Detalle del envío creado
}

400: Bad Request Un error en los datos impide crear el envío

{
    // El detalle indicará detalladamente el motivo del error.
}

Crear envío indicando paquetes a despachar

Permite crear un envío indicando un conjunto de paquetes a despachar. Queda de tu lado la agrupación de productos en paquetes, si es que debes enviar más de un producto.

La utilización de múltiples paquetes sirve para cuando en un mismo envío debes despachar múltiples bultos (por ejemplo si estás enviando un colchón y un sommier).

Crear envío (basado en packages)

POST /v2/shipments

Este request te permitirá crear envíos indicando los articulos que son parte del despacho. El sistema los agrupará en paquetes automáticamente, según las reglas definidas en la cuenta.

Request Body

Name	Type	Description
account_id*	int	ID de la cuenta
origin_id*	int	ID del origen del envío
logistic_type	string	Código de la forma de despacho del envío. Ejemplo: carrier_dropoff Se recomienda explicitarlo basado en los resultados obtenidos en la cotización utilizar la opcion de envio deseada
service_type	string	Código de la forma de entrega del envío. Ejemplo: standard_delivery Se recomienda explicitarlo basado en los resultados obtenidos en la cotización utilizar la opcion de envio deseada
carrier_id	int	ID del transporte que hará la entrega. Se recomienda explicitarlo basado en los resultados obtenidos en la cotización.
source	string (100)	Utilizado en algunas integraciones para identificar el canal de venta.
declared_value*	float	Valor declarado del envío. Monto que se asegurará. Para no utilizar seguro se debe enviar en cero.
destination.name*	string (100)	Nombre y apellido del destinatario
destination.street*	string (100)	Calle del domicilio de entrega. Requerido solo en entregas a domicilio.
destination.street_number*	string (10)	Altura/nro de puerta del domicilio de entrega. Requerido solo en entregas a domicilio.
destination.street_extras (190)	string	Referencias adicionales del domicilio como piso, departamento, nro de lote, etc. Requerido solo en entregas a domicilio.
destination.point_id	int	ID de la ubicación de entrega. Requerido solo cuando la entrega es en un punto de entrega.
destination.document*	string (50)	Número de documento (DNI, RUT, o lo que corresponda) del destinatario
destination.email*	email (150)	Dirección de correo electrónico del destinatario
destination.phone*	string (50)	Número de contacto del destinatario
destination.state*	string	Nombre del Estado del domicilio del destinatario. AR: provincia CL: región CO: departamento MX: estado Requerido solo en entregas a domicilio.
destination.city*	string	Nombre de la ciudad del domicilio del destinatario. AR: localidad CL: comuna CO: ciudad MX: ciudad Requerido solo en entregas a domicilio.
destination.zipcode*	string	Codigo postal de la dirección de destino. Requerido solo en entregas a domicilio. Dato no requerido en Chile y Colombia.
destination.country	string	Código ISO 3166-1 alfa-2 del país Argentina: AR Chile: CL Colombia: CO México: MX
destination*	object	Objeto con datos del destinatario
packages*	array[package]	Array de objetos Package. El máximo de paquetes por envío es 99.
packages.*.weight*	int	Peso en gramos.
packages.*.classification_id	int	ID de clasificación de producto del paquete. Si se omite se utilizará la clasificación General (1). Ver clasificaciones disponibles.
packages.*.height*	int	Alto del paquete, en centímetros.
packages.*.width*	int	Ancho del paquete, en centímetros.
packages.*.length*	int	Largo del paquete, en centímetros.
packages.*.description_1*	string (60)	Descripción del contenido (linea 1)
packages.*.description_3	string (60)	Descripción del contenido (linea 3)
packages.*.description_2	string (60)	Descripción del contenido (linea 2)
external_id*	string (30)	ID del envío en tus sistemas. Es para tu propia referencia.

201: Created El envío se crea correctamente.

{
    // Detalle del envío creado
}

400: Bad Request Un error en los datos impide crear el envío

{
    // El detalle indicará detalladamente el motivo del error.
}

Devoluciones

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 /v2/shipments/{id}/return/quote

Este request te permitirá obtener cotizaciones para una devolución de un envío, indicando los ítems específicos que forman parte de la devolución.

Path Parameters

Name	Type	Description
id*	int	ID del envío a cotizar una devolución

Request Body

Name	Type	Description
account_id*	int	ID de la cuenta
declared_value*	float	Valor declarado total del contenido. Monto que se utilizará para el seguro. Si no se va a asegurar el contenido, se puede indicar el valor 0.
packages*	array	Array de objetos packages.
packages.*.id*	int	ID del paquete del envio original que se quiere devolver
packages.*.items	array	Opcionalmente, se puede indicar qué items de un paquete se quieren incluir en la devolucion. Si se omite, se asume que se quiere devolver el paquete completo
package.*.items.*.id	int	ID de item del paquete

200: OK Una respuesta correcta contendrá este detalle.

// Request
{
	"account_id": "2",
	"declared_value": 629,
	"packages": [
		{
			"id": 76524,
		},
		{
			"id": 76525,
      "items":[
      {
        "id": 986,
      },
      {
        "id": 987,
      }
		}
	],
}

// Response
{
  "sorted_by": "price",
  "destination": {
    "id": 1735,
    "city": "San Isidro",
    "state": "Buenos Aires",
    "zipcode": "1642"
  },
  "packages": [
    {
      "id": 76524
      "weight": 10000,
      "height": 10,
      "width": 50,
      "length": 30,
      "volume": 15000,
      "sku_id": null,
      "classification_id": 1,
      "items": [
        {
          "id": 984
          "weight": 500,
          "height": 8,
          "width": 8,
          "length": 8,
          "sku": "ITEM1"
        }
      ],
      "container": null
    },
    {
      "id": 76524
      "weight": 10000,
      "height": 10,
      "width": 50,
      "length": 30,
      "volume": 15000,
      "sku_id": null,
      "classification_id": 1,
      "items": [
        {
          "id": 986
          "weight": 500,
          "height": 8,
          "width": 8,
          "length": 8,
          "sku": "ITEM1"
        },
        {
          "id": 987
          "weight": 500,
          "height": 8,
          "width": 8,
          "length": 8,
          "sku": "ITEM2"
        }
      ],
      "container": {
        "id": 2,
        "description": "Caja Mediana 2",
        "inner_width": 14,
        "inner_length": 11,
        "inner_height": 8,
        "outer_width": 15,
        "outer_length": 12,
        "outer_height": 9,
        "empty_weight": 100,
        "max_weight": 3000
      }
    }
  ],
  "results": {
    "standard_delivery": {
      "selectable": true,
      "impediments": null,
      "logistic_type": "carrier_dropoff",
      "carrier": {
        "id": 205,
        "name": "Leset",
        "rating": 0.95,
        "logo": "https:\/\/zippin-ar.s3.amazonaws.com\/carriers\/leset\/9Bw6vmnLH2ZUvKTdAcQtqJRkvkZdJTqcPlR9nwYU.png"
      },
      "service_type": {
        "id": 10,
        "code": "return_origin",
        "name": "Devolución a origen",
        "is_urgent": 0
      },
      "delivery_time": {
        "min": 3,
        "max": 7
      },
      "amounts": {
        "price_shipment": 315.79,
        "price_insurance": 8.18,
        "price": 323.97,
        "price_incl_tax": 392
      },
      "rate": {
        "source": "tariff",
        "id": 12957,
        "tariff_id": 71
      },
      "tags": [
        "cheapest",
        "fastest"
      ]
    }
  },
  "all_results": [
    {
      "selectable": true,
      "impediments": null,
      "logistic_type": "carrier_dropoff",
      "carrier": {
        "id": 205,
        "name": "Leset",
        "rating": 0.95,
        "logo": "https:\/\/zippin-ar.s3.amazonaws.com\/carriers\/leset\/9Bw6vmnLH2ZUvKTdAcQtqJRkvkZdJTqcPlR9nwYU.png"
      },
      "service_type": {
        "id": 10,
        "code": "return_origin",
        "name": "Devolución a origen",
        "is_urgent": 0
      },
      "delivery_time": {
        "min": 3,
        "max": 7
      },
      "amounts": {
        "price_shipment": 315.79,
        "price_insurance": 8.18,
        "price": 323.97,
        "price_incl_tax": 392
      },
      "rate": {
        "source": "tariff",
        "id": 12957,
        "tariff_id": 71
      },
      "tags": [
        "cheapest",
        "fastest"
      ]
    },
    {
      "selectable": true,
      "impediments": null,
      "logistic_type": "carrier_pickup",
      "carrier": {
        "id": 220,
        "name": "Malargue",
        "rating": 0.94,
        "logo": "https:\/\/zippin-ar.s3.amazonaws.com\/carriers\/malargue\/gzHM0KZOWMtDbd0svUiRJpiExH9uIQsAa3n8auke.png"
      },
      "service_type": {
        "id": 10,
        "code": "return_origin",
        "name": "Devolución a origen",
        "is_urgent": 0
      },
      "delivery_time": {
        "min": 5,
        "max": 10
      },
      "amounts": {
        "price_shipment": 725.7,
        "price_insurance": 8.18,
        "price": 733.88,
        "price_incl_tax": 888
      },
      "rate": {
        "source": "tariff",
        "id": 13050,
        "tariff_id": 113
      },
      "tags": []
    }
  ]
}

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 devolución

POST /v2/shipments/{id}/return

Path Parameters

Name	Type	Description
id*	int	ID del envío a del cual crear una devolución

Request Body

Name	Type	Description
account_id*	int	ID de la cuenta
declared_value*	float	Valor declarado total del contenido. Monto que se utilizará para el seguro. Si no se va a asegurar el contenido, se puede indicar el valor 0.
packages*	array	Array de objetos packages.
packages.*.id*	int	ID del paquete del envio original que se quiere devolver
packages.*.items	array	Opcionalmente, se puede indicar qué items de un paquete se quieren incluir en la devolucion. Si se omite, se asume que se quiere devolver el paquete completo
package.*.items.*.id	int	ID de item del paquete
carrier_id	int	Para indicar con qué transporte crear la devolución (sale de la cotización).
logistic_type*	string	Código del modo de despacho (sale de la cotización) Ej. carrier_dropoff
service_type*	string	Código del tipo de servicio (sale de la cotización) Ej. return_origin

201: Created Una respuesta correcta contendrá este detalle.

// Request
{
	"account_id": "2",
	"declared_value": 9015,
  "service_type": "return_origin",
  "logistic_type": "carrier_dropoff",
	"packages": [
		{
			"id": 76524,
		},
		{
			"id": 76525,
      "items":[
      {
        "id": 986,
      },
      {
        "id": 987,
      }
		}
	],
}

// Response
{
  "id": 151060,
  "external_id": "testcosts",
  "delivery_id": "0999-00151060",
  "carrier_tracking_id": null,
  "created_at": "2020-06-09T15:19:07+0000",
  "account_id": 2,
  "parent_shipment_id": null,
  "logistic_type": "carrier_dropoff",
  "service_type": "return_origin",
  "carrier": {
    "id": 8,
    "name": "La Sevillanita",
    "logo": "https:\/\/zippin-ar.s3.amazonaws.com\/carriers\/la-sevillanita\/Kt4qo3TsENegNCCnrW70OxQhBqbo7uyfemNRT5bH.png"
  },
  "status": "new",
  "status_name": "Procesando",
  "tracking": "http:\/\/app.zippin.com.ar\/track\/151060",
  "tracking_external": "http:\/\/app.zippin.com.ar\/track\/2\/testcosts",
  "destination": {
    "name": "TEST",
    "document": "3333",
    "street": "TEST",
    "street_number": "222",
    "street_extras": "TEST",
    "city": "Salta",
    "state": "Salta",
    "zipcode": "4400",
    "phone": "00000",
    "email": "[e-mail]"
  },
  "origin": {
    "id": 25,
    "name": "Origen Demo",
    "document": "22222222",
    "street": "Av Luis Maria Campos",
    "street_number": "877",
    "street_extras": "PRUEBA",
    "city": "Capital Federal",
    "state": "Capital Federal",
    "zipcode": "1005",
    "phone": "22222222",
    "email": "[e-mail]"
  },
  "declared_value": 9015,
  "price": 869.42,
  "price_incl_tax": 1052,
  "total_weight": 1100,
  "total_volume": 4080,
  "packages": [
  {
    "internal_id": 76524,
    "sku_id": null,
    "weight": 1100,
    "height": 12,
    "width": 20,
    "length": 17,
    "volume": 4080,
    "description_1": "1 producto",
    "description_2": "Test 1",
    "description_3": null,
    "classification": {
      "id": 1,
      "name": "General"
    },
    "items": [
      {
        "sku": null,
        "description": "985",
        "must_keep_vertical": 0,
        "weight": 500,
        "width": 8,
        "length": 8,
        "height": 8,
        "pos_x": 0,
        "pos_y": 0,
        "pos_z": 0
      }
    ],
    "container": null,
    {
      "internal_id": 76525,
      "sku_id": null,
      "weight": 1100,
      "height": 12,
      "width": 20,
      "length": 17,
      "volume": 4080,
      "description_1": "2 productos",
      "description_2": "Test 1",
      "description_3": null,
      "classification": {
        "id": 1,
        "name": "General"
      },
      "items": [
        {
          "sku": null,
          "description": "986",
          "must_keep_vertical": 0,
          "weight": 500,
          "width": 8,
          "length": 8,
          "height": 8,
          "pos_x": 0,
          "pos_y": 0,
          "pos_z": 0
        },
        {
          "sku": null,
          "description": "987",
          "must_keep_vertical": 0,
          "weight": 500,
          "width": 8,
          "length": 8,
          "height": 8,
          "pos_x": 8,
          "pos_y": 0,
          "pos_z": 0
        }
      ],
      "container": {
        "id": 1,
        "description": "Test 1",
        "outer_width": 20,
        "outer_height": 12,
        "outer_length": 17,
        "inner_width": 19,
        "inner_length": 16,
        "inner_height": 11,
        "max_weight": 5000
      }
    }
  ],
  "tags": []
}