> 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/cotizar-envios.md). # Cotizar Envíos {% hint style="warning" %} Los endpoints de cotización utilizan **rate limiting** :orange\_circle:**Medio**\ [Ver más sobre límites de requests](/envios/principios/limites-de-requests.md) {% endhint %} La cotización es el proceso mediante el cual se obtienen opciones para hacer un envío. En Zipnova existen múltiples maneras de hacer un envío, combinando diferentes **formas de despacho** (`logistic_type`) y **formas de entrega** (`service_type`). En los resultados de cotización verás todas las opciones disponibles en tu cuenta para hacer el envío, con los distintos transportes disponibles. {% hint style="info" %} 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](https://ayuda.zippin.app/automatizaciones), utilizando el atributo source como criterio de filtrado. {% endhint %} ## Cotizar envío > Obtiene las opciones de envío disponibles con sus costos y tiempos estimados.\ > \ > \*\*items vs packages — debes usar uno u otro, nunca ambos:\*\*\ > \ > \- \*\*\`items\` (recomendado):\*\* Lista de unidades individuales de productos. El sistema las empaqueta automáticamente según el modo \`type\_packaging\`. Cada item puede referenciar un SKU de la cuenta (con \`sku\`) o bien declarar explícitamente sus dimensiones y peso.\ > \- \*\*\`packages\`:\*\* Lista de bultos ya definidos con dimensiones explícitas. Útil cuando el empaquetado ya está resuelto del lado del integrador. Cada paquete puede referenciar un SKU (\`sku\` / \`sku\_id\`) para obtener sus dimensiones, o declararlas manualmente. Opcionalmente puede incluir \`items\` internos si se especifica un \`container\_id\`. ```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":{"QuoteResult":{"title":"Resultado de cotización","properties":{"selectable":{"description":"Indica si esta opción puede usarse para crear un envío","type":"boolean"},"impediments":{"description":"Motivos por los que la opción no es seleccionable. Null cuando selectable es true","type":"array","items":{"type":"string"},"nullable":true},"logistic_type":{"description":"Tipo logístico de la opción (e.g. xd_dropoff, carrier_dropoff, carrier_pickup)","type":"string"},"carrier":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"rating":{"description":"Puntaje de calidad del transportista (0-5)","type":"number","format":"float"},"logo":{"type":"string","nullable":true}},"type":"object"},"service_type":{"properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"is_urgent":{"type":"boolean"}},"type":"object"},"delivery_time":{"properties":{"warning":{"description":"Aviso de deprecación de min/max","type":"string"},"min":{"description":"Días hábiles mínimos estimados (deprecado)","type":"integer"},"max":{"description":"Días hábiles máximos estimados (deprecado)","type":"integer"},"estimated_delivery":{"description":"Fecha estimada de entrega (ISO 8601)","type":"string","format":"date-time"},"estimation_expires_at":{"description":"Fecha de vencimiento de esta estimación (ISO 8601)","type":"string","format":"date-time"},"times":{"description":"Desglose de tiempos en formato de duración ISO 8601 (e.g. P2D = 2 días)","properties":{"preparation":{"type":"string"},"crossdocking":{"type":"string"},"carrier":{"properties":{"min":{"type":"string"},"max":{"type":"string"}},"type":"object"},"total":{"properties":{"min":{"type":"string"},"max":{"type":"string"}},"type":"object"}},"type":"object"}},"type":"object"},"amounts":{"properties":{"price_shipment":{"description":"Precio del flete sin seguro","type":"number","format":"float"},"price_insurance":{"description":"Precio del seguro","type":"number","format":"float"},"price":{"description":"Precio total sin impuestos que paga el cliente","type":"number","format":"float"},"price_incl_tax":{"description":"Precio total con impuestos que paga el cliente","type":"number","format":"float"},"seller_price":{"description":"Precio neto del seller sin impuestos","type":"number","format":"float"},"seller_price_incl_tax":{"description":"Precio neto del seller con impuestos","type":"number","format":"float"}},"type":"object"},"rate":{"properties":{"source":{"description":"Fuente de la tarifa aplicada","type":"string"},"id":{"description":"ID de la tarifa","type":"integer"},"tariff_id":{"description":"ID del tariff al que pertenece la tarifa","type":"integer"}},"type":"object"},"tags":{"description":"Etiquetas destacadas del resultado (cheapest, fastest)","type":"array","items":{"type":"string","enum":["cheapest","fastest"]}},"pickup_points":{"description":"Hasta 5 puntos de retiro cercanos al destino. Solo presente cuando service_type.code es pickup_point","type":"array","items":{"properties":{"point_id":{"type":"integer"},"description":{"type":"string"},"open_hours":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"location":{"properties":{"street":{"type":"string"},"street_number":{"type":"string"},"street_extras":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string"},"zipcode":{"type":"string","nullable":true},"geolocation":{"properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"},"distance":{"description":"Distancia desde el origen en metros","type":"integer"}},"type":"object"}},"type":"object"}},"type":"object"},"nullable":true},"dropoff_points":{"description":"Hasta 5 puntos de dropoff cercanos al origen. Solo presente cuando include_dropoff_points=1 y el logistic_type es carrier_dropoff, xd_dropoff o gateway_dropoff","type":"array","items":{"properties":{"name":{"type":"string"},"default_logistic_type":{"type":"string","nullable":true},"address":{"properties":{"street":{"type":"string"},"street_number":{"type":"string"},"street_extras":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string"},"geolocation":{"properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}},"type":"object"}},"type":"object"}},"type":"object"},"nullable":true}},"type":"object"}}},"paths":{"/shipments/quote":{"post":{"tags":["Envíos"],"summary":"Cotizar envío","description":"Obtiene las opciones de envío disponibles con sus costos y tiempos estimados.\n\n**items vs packages — debes usar uno u otro, nunca ambos:**\n\n- **`items` (recomendado):** Lista de unidades individuales de productos. El sistema las empaqueta automáticamente según el modo `type_packaging`. Cada item puede referenciar un SKU de la cuenta (con `sku`) o bien declarar explícitamente sus dimensiones y peso.\n- **`packages`:** Lista de bultos ya definidos con dimensiones explícitas. Útil cuando el empaquetado ya está resuelto del lado del integrador. Cada paquete puede referenciar un SKU (`sku` / `sku_id`) para obtener sus dimensiones, o declararlas manualmente. Opcionalmente puede incluir `items` internos si se especifica un `container_id`.","operationId":"7ee582cc79905860fc252e3e01209b0f","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["account_id","source","declared_value","destination"],"properties":{"account_id":{"description":"ID de la cuenta","type":"integer"},"origin_id":{"description":"ID del address book de origen. Si se omite, se usa el origen por defecto de la cuenta.","type":"integer"},"source":{"description":"Identificador de la fuente que genera la cotización (ej. nombre de la integración). Máximo 150 caracteres.","type":"string"},"destination":{"description":"Destino del envío. Identificar por `id` (ciudad) o por `city` + `state`. El `zipcode` puede ser requerido según el país.","properties":{"city":{"description":"Nombre de la ciudad. Requerido si no se usa `id`.","type":"string"},"state":{"description":"Nombre de la provincia/estado. Requerido junto con `city`.","type":"string"},"zipcode":{"description":"Código postal. Requerido en países donde aplica.","type":"string"},"street":{"description":"Calle del destinatario (opcional).","type":"string"},"street_number":{"description":"Número de calle del destinatario (opcional).","type":"string"},"id":{"description":"ID de ciudad (opcional, si se conoce). Alternativa a city+state.","type":"integer"}},"type":"object"},"declared_value":{"description":"Valor declarado del envío (numérico, mínimo 0). Si se indica en cero, el envío no contará con cobertura del seguro.","type":"number"},"items":{"description":"Array de unidades de productos a enviar. **Usar `items` O `packages`, nunca ambos.** El sistema empaqueta automáticamente los ítems según `type_packaging`. Máximo 1000 ítems.","type":"array","items":{"properties":{"sku":{"description":"Código SKU del producto registrado en la cuenta. Si se provee y es válido, se obtienen dimensiones, peso y clasificación del producto o SKU que coincida. Si no se provee o no se encuentra, se deben declarar `weight`, `height`, `width` y `length`.","type":"string"},"weight":{"description":"Peso en gramos. Requerido si no se provee `sku` válido. Entero entre 10 y 10.000.000.","type":"integer"},"height":{"description":"Alto en cm. Requerido si no se provee `sku` válido. Entero entre 1 y 5000.","type":"integer"},"width":{"description":"Ancho en cm. Requerido si no se provee `sku` válido. Entero entre 1 y 5000.","type":"integer"},"length":{"description":"Largo en cm. Requerido si no se provee `sku` válido. Entero entre 1 y 5000.","type":"integer"},"classification_id":{"description":"ID de clasificación de mercadería. Si no se provee, se infiere de la descripción o se usa el valor por defecto (general).","type":"string"},"description":{"description":"Descripción del ítem. Si se omite, se usa el nombre del SKU o un valor genérico.","type":"string"},"must_keep_vertical":{"description":"Indica si el ítem debe mantenerse en posición vertical durante el transporte.","type":"boolean"}},"type":"object"}},"packages":{"description":"Array de bultos con dimensiones ya definidas. **Usar `packages` O `items`, nunca ambos.** Cada bulto puede referenciar un SKU para obtener sus dimensiones, o declararlas manualmente.","type":"array","items":{"properties":{"sku":{"description":"Código SKU del producto. Si se provee y es válido, sus dimensiones y clasificación se obtienen automáticamente. Incompatible con `items` internos.","type":"string"},"sku_id":{"description":"ID numérico del SKU. Alternativa a `sku`. Incompatible con `items` internos.","type":"integer"},"weight":{"description":"Peso del bulto en gramos. Requerido si no se provee `sku`, `sku_id` ni `container_id`. Entero entre 10 y 10.000.000.","type":"integer"},"height":{"description":"Alto del bulto en cm. Requerido si no se provee `sku`, `sku_id` ni `container_id`. Entero entre 1 y 5000.","type":"integer"},"width":{"description":"Ancho del bulto en cm. Requerido si no se provee `sku`, `sku_id` ni `container_id`. Entero entre 1 y 5000.","type":"integer"},"length":{"description":"Largo del bulto en cm. Requerido si no se provee `sku`, `sku_id` ni `container_id`. Entero entre 1 y 5000.","type":"integer"},"classification_id":{"description":"Clasificación de la mercadería. Puede ser el ID numérico (ej. `1`) o el código de clasificación (ej. `\"default\"`). Requerido si no se provee `sku`, `sku_id` ni `container_id`.","type":"string"},"description_1":{"description":"Descripción del bulto (línea 1). Máximo 60 caracteres.","type":"string"},"description_2":{"description":"Descripción opcional del bulto (línea 2). Máximo 60 caracteres.","type":"string"},"description_3":{"description":"Descripción opcional del bulto (línea 3). Máximo 60 caracteres.","type":"string"},"container_id":{"description":"ID de un contenedor predefinido habilitado en la cuenta. Si se provee, se requiere el array `items` con los productos que van dentro.","type":"integer"},"items":{"description":"Ítems dentro del bulto. Requerido si se usa `container_id`. El sistema calcula las dimensiones finales del bulto a partir del contenedor y los ítems.","type":"array","items":{"properties":{"sku":{"description":"Código SKU del ítem. Si se provee y es válido, se obtienen dimensiones y peso del SKU.","type":"string"},"weight":{"description":"Peso en gramos. Requerido si no se provee `sku` válido. Entero entre 10 y 10.000.000.","type":"integer"},"height":{"description":"Alto en cm. Requerido si no se provee `sku` válido. Entero entre 1 y 5000.","type":"integer"},"width":{"description":"Ancho en cm. Requerido si no se provee `sku` válido. Entero entre 1 y 5000.","type":"integer"},"length":{"description":"Largo en cm. Requerido si no se provee `sku` válido. Entero entre 1 y 5000.","type":"integer"},"classification_id":{"description":"ID de clasificación de mercadería.","type":"string"},"description":{"description":"Descripción del ítem.","type":"string"},"must_keep_vertical":{"description":"Indica si el ítem debe mantenerse vertical.","type":"boolean"}},"type":"object"}}},"type":"object"}},"type_packaging":{"description":"Modo de empaquetado, aplicable solo cuando se usa `items`. `dynamic`: el sistema elige los mejores contenedores disponibles. `boxes`: usa los contenedores configurados en la cuenta. `none`: cada ítem es un bulto individual.","type":"string","enum":["dynamic","boxes","none"]},"logistic_type":{"description":"Filtra los resultados por tipo logístico (ej. `carrier_pickup`, `carrier_dropoff`).","type":"string"},"service_type":{"description":"Filtra los resultados por código de tipo de servicio.","type":"string"},"sort_by":{"description":"Criterio de ordenamiento de los resultados.","type":"string","enum":["price","rating","time"]},"avoid_rules":{"description":"Si es `true`, omite la aplicación de reglas de negocio de la cuenta.","type":"boolean"},"include_dropoff_points":{"description":"Si es `1`, incluye puntos de dropoff cercanos al origen en cada resultado que aplique.","type":"integer","enum":[0,1]}},"type":"object"}}}},"responses":{"200":{"description":"Lista de opciones de envío disponibles con precios y tiempos","content":{"application/json":{"schema":{"properties":{"sorted_by":{"description":"Criterio de ordenamiento aplicado a los resultados","type":"string","enum":["price","rating","time"]},"origin":{"description":"Ubicación del origen resuelta internamente","properties":{"id":{"type":"integer"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"zipcode":{"type":"string","nullable":true},"geolocation":{"properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}},"type":"object"}},"type":"object"},"destination":{"description":"Ubicación del destino resuelta internamente","properties":{"id":{"type":"integer"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"zipcode":{"type":"string","nullable":true},"geolocation":{"properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}},"type":"object"}},"type":"object"},"declared_value":{"type":"number","format":"float"},"supplier_id":{"description":"ID del proveedor dropshipping asociado al origen, si aplica","type":"integer","nullable":true},"packages":{"description":"Bultos resultantes del proceso de empaquetado, con sus dimensiones y clasificación finales","type":"array","items":{"properties":{"weight":{"type":"integer"},"height":{"type":"integer"},"width":{"type":"integer"},"length":{"type":"integer"},"classification_id":{"type":"integer"}},"type":"object"}},"results":{"description":"Objeto indexado por `service_type.code` con la mejor opción seleccionable de cada tipo de servicio, según el criterio de ordenamiento. Subset de `all_results`.","type":"object","additionalProperties":{"$ref":"#/components/schemas/QuoteResult"}},"all_results":{"description":"Todas las opciones de envío disponibles, incluyendo las no seleccionables","type":"array","items":{"$ref":"#/components/schemas/QuoteResult"}}},"type":"object"}}}},"400":{"description":"Datos inválidos o cuenta inactiva"},"403":{"description":"Sin permiso para cotizar en esta cuenta"},"422":{"description":"Error de validación"}}}}}} ``` ### Respuesta de cotización La respuesta de la cotización incluirá los siguientes elementos:
destination Describe la localidad/comuna/ciudad de destino que fue identificada según los datos suministrados en el request.
packages Sirve como referencia para entender cómo se construyeron los paquetes que conforman el envío. Si al cotizar indicaste paquetes, reflejará la misma información del request. En cambio, si indicaste items, aquí te mostrará cómo han sido agrupados esos items en paquetes.
results/all_results Aquí estarán las distintas opciones para poder realizar un envío. En el objeto `results` tendrás un solo resultado ganador por cada `service_type` (forma de entrega). En el objeto `all_results` tendrás todos los resultados disponibles.
#### Atributos de un result
AtributoDescripción
service_typeTipo de servicio: la forma de entrega del envío.
El atributo code deberá ser usado al crear el envío (ej. standard_delivery)
logistic_typeModo de despacho: cómo se va a despachar el envío
carrierEl transporte que hace la entrega. El atributo id deberá ser usado para crear el envío.
delivery_timeIndica el tiempo de entrega.
estimated_delivery indica la fecha máxima de entrega
estimation_expires_at indica cuando vence la estimación
times: indica distintos tiempos del proceso de entrega, en formato ISO8601 de duración.
amounts

Indica aspectos del precio del envío.
price es el precio sin IVA que debe pagar el comprador
price_incl_tax es el precio con IVA que debe pagar el comprador
seller_price es el precio sin IVA que paga el vendedor
seller_price_incl_tax es el precio con IVA que paga el vendedor
price_shipment refleja la porción del precio del envío que es pura del envío
price_insurance refleja la porción del precio del envío que corresponde al seguro y depende del valor declarado.

price y seller_price por lo general son lo mismo, salvo en algunos casos:

  • Cuando el resultado es de Flota Propia o Contrato Propio, el price refleja el precio de la tarifa y seller_price lo que cobra Zippin.
  • Cuando haya una regla que modifiquen el precio del envio, esa modificación se ve reflejada en price, mientras que seller_price mantiene el valor original.
pickup_pointsEs un array con puntos habilitados para la entrega del envío, cuando el tipo de servicio es pickup_point.
De cada punto es importante obtener el point_id, que deberá ser enviado al crear el envío para indicar la sucursal de entrega.