# Cotización y creación de ordenes

La cotización de envíos funciona igual que cualquier otra cotización. La única diferencia es que la autenticación se debe hacer con el access token, en vez de credenciales de la cuenta, y que luego, **en vez de crear un envío, se deberá crear una Orden de Marketplace**.

## Cotización

Revisa la [documentación de la cotización](https://docs.zipnova.com/envios/recursos-api/envios/cotizar-envios).

{% hint style="warning" %}
Recuerda, no se deberían crear envíos en forma directa, si no Ordenes de Marketplace.
{% endhint %}

## Creación de Ordenes de Marketplace

Una vez que el comprador realice su compra, y haya elegido una opción de entrega, deberías crear una orden en Zipnova Envíos para que el vendedor pueda verla y luego pueda crearse el envío a partir de ella.

### Requerimientos

Para crear la orden, deberás contar con algunos datos del envío, que surgen de la opción seleccionada por el comprador, entre la opciones disponibles de una cotización.

* Transporte elegido (carrier\_id)
* Forma de despacho (logistic\_type)
* Tipo de servicio de entrega (service\_type)
* Origen del vendedor (origin\_id)
* Punto de entrega (point\_id) - si se eligió una entrega en pickup point.

## Crear órden

> Crea una nueva órden de marketplace en Zipnova.\
> \
> \*\*Creación automática de envío\*\*: Cuando \`create\_shipment=true\`, el sistema intentará crear un envío a partir de la órden de forma sincrónica. la órden debe tener una dirección de origen válida (indicada en \`shipping.origin\_id\` o, en su defecto, la primera dirección de la cuenta). Si no existe una ruta disponible para el destino, se retorna un error 422.\
> \
> \*\*Dirección de entrega vs. punto de retiro\*\*: Se debe proveer \`delivery.address\` o \`delivery.point\_id\`. Usar \`delivery.point\_id\` cuando el tipo de servicio sea \`pickup\_point\`; en caso contrario, proveer la dirección completa.\
> \
> \*\*Permiso requerido\*\*: \`orders.create\`

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Shipping API V2","version":"2.0.0"},"tags":[{"name":"Ventas","description":"Gestión de ventas"}],"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":{"OrderApiResource":{"title":"Pedido","description":"Representa un pedido de marketplace y sus detalles de envío asociados.","properties":{"id":{"description":"Identificador único del pedido","type":"integer"},"account_id":{"description":"ID de la cuenta vendedora propietaria del pedido","type":"integer"},"channel":{"description":"Información del canal de venta","properties":{"type":{"description":"Tipo de canal (ej. marketplace)","type":"string"},"marketplace":{"description":"Código del marketplace","type":"string","nullable":true},"created_at":{"description":"Fecha de creación del pedido en el canal","type":"string","format":"date-time"},"paid_at":{"description":"Fecha de pago del pedido en el canal","type":"string","format":"date-time","nullable":true},"data":{"description":"Datos adicionales específicos del canal","type":"object","nullable":true}},"type":"object"},"completed_at":{"description":"Fecha y hora en que el pedido fue marcado como completado (pago confirmado)","type":"string","format":"date-time","nullable":true},"shipment_requested_at":{"description":"Fecha y hora en que se solicitó la creación del envío para este pedido","type":"string","format":"date-time","nullable":true},"saved_origin_id":{"description":"ID de la dirección del libro de direcciones utilizada como origen del envío","type":"integer","nullable":true},"logistic_type":{"description":"Código del tipo logístico (ej. cross_docking, fulfillment)","type":"string","nullable":true},"carrier_id":{"description":"ID del transportista asignado a este pedido","type":"integer","nullable":true},"service_type_id":{"description":"ID del tipo de servicio asignado a este pedido","type":"integer","nullable":true},"destination":{"oneOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true,"description":"Dirección de destino de entrega"},"items":{"description":"Ítems del pedido","type":"array","items":{"properties":{"id":{"description":"ID del ítem","type":"integer"},"qty":{"description":"Cantidad pedida","type":"integer"},"unit_price":{"description":"Precio unitario del ítem","type":"number"},"currency":{"description":"Código de moneda (ISO 4217)","type":"string"},"product_id":{"description":"ID interno del producto si está vinculado al catálogo","type":"integer","nullable":true},"data":{"description":"Datos del producto provenientes del pedido (SKU y nombre)","properties":{"sku":{"description":"SKU del producto","type":"string"},"name":{"description":"Nombre del producto","type":"string"}},"type":"object","nullable":true}},"type":"object"}},"total_paid_amount":{"description":"Monto total pagado por el comprador","type":"number","nullable":true},"total_shipping_paid_amount":{"description":"Monto de envío pagado por el comprador","type":"number","nullable":true},"currency":{"description":"Código de moneda del pedido (ISO 4217)","type":"string","nullable":true},"tags":{"description":"Etiquetas asociadas al pedido","type":"array","items":{"type":"string"},"nullable":true},"shipments":{"description":"Envíos vinculados a este pedido (solo se incluyen cuando se cargan explícitamente)","type":"array","items":{"properties":{"id":{"description":"ID del envío","type":"integer"},"external_id":{"description":"ID de seguimiento externo del transportista","type":"string","nullable":true},"tracking_id":{"description":"ID de seguimiento de Zipnova","type":"string"},"status":{"description":"Código del estado actual del envío","type":"string"},"tracking_url":{"description":"URL pública de seguimiento","type":"string"}},"type":"object"}},"created_at":{"description":"Fecha y hora en que se creó el registro en Zipnova","type":"string","format":"date-time"},"updated_at":{"description":"Fecha y hora de la última actualización del registro","type":"string","format":"date-time"}},"type":"object"},"Address":{"title":"Dirección de orden","description":"Definición de una dirección utilizada en órdenes y envíos","properties":{"id":{"description":"Identificador","type":"integer"},"name":{"description":"Nombre","type":"string"},"street":{"description":"Calle","type":"string"},"street_number":{"description":"Número","type":"string"},"street_extras":{"description":"Extras (piso, dpto, etc.)","type":"string"},"zipcode":{"description":"Código postal","type":"string"},"phone":{"description":"Teléfono","type":"string"},"email":{"description":"Correo electrónico","type":"string"},"document":{"description":"Documento/CUIT","type":"string"},"city":{"description":"Ciudad/Localidad/Comuna","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"state":{"description":"Provincia/Región/Estado","properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"country":{"description":"País","properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"location_latitude":{"description":"Latitud","type":"number"},"location_longitude":{"description":"Longitud","type":"number"},"location_type":{"description":"Tipo de ubicación","type":"string","nullable":true},"location_metadata":{"description":"Metadata de ubicación","type":"string","nullable":true},"is_accurate":{"description":"Indica si la geocodificación es precisa","type":"boolean","nullable":true},"created_at":{"description":"Fecha de creación","type":"string","format":"date-time"},"updated_at":{"description":"Fecha de última actualización","type":"string","format":"date-time"},"confirmed_at":{"description":"Fecha de confirmación de ubicación","type":"string","format":"date-time","nullable":true}},"type":"object"}}},"paths":{"/orders":{"post":{"tags":["Ventas"],"summary":"Crear órden","description":"Crea una nueva órden de marketplace en Zipnova.\n\n**Creación automática de envío**: Cuando `create_shipment=true`, el sistema intentará crear un envío a partir de la órden de forma sincrónica. la órden debe tener una dirección de origen válida (indicada en `shipping.origin_id` o, en su defecto, la primera dirección de la cuenta). Si no existe una ruta disponible para el destino, se retorna un error 422.\n\n**Dirección de entrega vs. punto de retiro**: Se debe proveer `delivery.address` o `delivery.point_id`. Usar `delivery.point_id` cuando el tipo de servicio sea `pickup_point`; en caso contrario, proveer la dirección completa.\n\n**Permiso requerido**: `orders.create`","operationId":"37204eaaf8d1f05eda434b439a620e5f","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["channel","account_id","external_id","created_at","total_amount","paid_amount","shipping_paid_amount","items"],"properties":{"channel":{"description":"Canal de venta en el formato \"marketplace:{code}\". Por el momento solo se aceptan canales de tipo marketplace.","type":"string"},"account_id":{"description":"ID de la cuenta vendedora a la que se asociará la órden. El usuario autenticado debe tener acceso a esta cuenta.","type":"integer"},"external_id":{"description":"ID de la órden en el sistema del marketplace. Máximo 30 caracteres.","type":"string"},"source":{"description":"Identificador de origen opcional para rastrear qué integración o sistema envió la órden. Máximo 20 caracteres.","type":"string","nullable":true},"created_at":{"description":"Fecha y hora ISO 8601 de cuando fue creado la órden originalmente en el marketplace.","type":"string","format":"date-time"},"total_amount":{"description":"Monto total de la órden (productos + envío).","type":"number"},"paid_amount":{"description":"Monto efectivamente pagado por el comprador.","type":"number"},"shipping_paid_amount":{"description":"Costo de envío pagado por el comprador (0 para envío gratuito).","type":"number"},"currency":{"description":"Código de moneda ISO 4217 para los montos de la órden. Por defecto, la moneda del país de la cuenta.","type":"string"},"create_shipment":{"description":"Cuando es true, se crea automáticamente un envío a partir de la órden de forma sincrónica. Por defecto false.","type":"boolean"},"shipping":{"description":"Preferencias de envío opcionales que guían la creación automática del envío.","properties":{"origin_id":{"description":"ID de una entrada del libro de direcciones a usar como origen del envío. Si no se provee y create_shipment=true, se utiliza la primera dirección de la cuenta.","type":"integer","nullable":true},"carrier_id":{"description":"Fuerza la asignación del envío a un transportista específico por ID.","type":"integer","nullable":true},"logistic_type":{"description":"Código del tipo logístico a utilizar (ej. cross_docking, fulfillment).","type":"string","nullable":true},"service_type":{"description":"Código del tipo de servicio a utilizar (ej. standard, express, pickup_point).","type":"string","nullable":true}},"type":"object"},"delivery":{"description":"Información del destinatario y dirección de entrega.","required":["recipient"],"properties":{"recipient":{"description":"La persona que recibirá el paquete.","required":["name","document","email","phone"],"properties":{"name":{"description":"Nombre completo del destinatario.","type":"string"},"document":{"description":"DNI o documento fiscal del destinatario. Máximo 50 caracteres.","type":"string"},"email":{"description":"Correo electrónico para notificaciones de envío.","type":"string","format":"email"},"phone":{"description":"Teléfono del destinatario. Máximo 50 caracteres.","type":"string"}},"type":"object"},"point_id":{"description":"ID de un punto de retiro del transportista. Requerido cuando shipping.service_type es pickup_point. Mutuamente excluyente con delivery.address.","type":"integer","nullable":true},"address":{"description":"Dirección de entrega. Requerida cuando no se provee delivery.point_id.","properties":{"street":{"description":"Nombre de la calle. Máximo 100 caracteres.","type":"string"},"street_number":{"description":"Número de la calle o \"S/N\" si no tiene número. Máximo 10 caracteres.","type":"string"},"street_extras":{"description":"Departamento, piso u otros datos adicionales de la dirección. Máximo 190 caracteres.","type":"string","nullable":true},"city":{"description":"Nombre de la ciudad. Requerido cuando se provee state o cuando no se usa point_id.","type":"string"},"state":{"description":"Nombre de la provincia o estado. Requerido cuando se provee city o cuando no se usa point_id.","type":"string"},"zipcode":{"description":"Código postal. Requerido en países donde es obligatorio (ej. Argentina). Máximo 10 caracteres.","type":"string"}},"type":"object"}},"type":"object"},"items":{"description":"Lista de productos incluidos en la órden. Se requiere al menos un ítem. Las dimensiones se utilizan para el armado de bultos y la cotización.","type":"array","items":{"required":["sku","name","weight","height","width","length"],"properties":{"sku":{"description":"Identificador SKU del producto.","type":"string"},"name":{"description":"Nombre del producto.","type":"string"},"qty":{"description":"Cantidad de este ítem en la órden. Por defecto 1.","type":"integer"},"unit_price":{"description":"Precio unitario del ítem. Por defecto 0.","type":"number"},"currency":{"description":"Código de moneda ISO 4217 para unit_price. Por defecto, la moneda del país de la cuenta.","type":"string"},"weight":{"description":"Peso del ítem en gramos. Mínimo 1.","type":"integer"},"height":{"description":"Alto del ítem en centímetros. Mínimo 1.","type":"integer"},"width":{"description":"Ancho del ítem en centímetros. Mínimo 1.","type":"integer"},"length":{"description":"Largo del ítem en centímetros. Mínimo 1.","type":"integer"}},"type":"object"}}},"type":"object"}}}},"responses":{"201":{"description":"Pedido creado exitosamente. Si create_shipment=true, el array shipments estará poblado con el envío generado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderApiResource"}}}},"400":{"description":"Tipo de canal inválido o cuenta no encontrada."},"401":{"description":"No autenticado."},"403":{"description":"Permisos insuficientes o sin acceso a la cuenta/marketplace indicado."},"422":{"description":"Error de validación o no se pudo crear el envío (ej. no hay ruta disponible para el destino). Ver el mensaje de error para más detalles."},"500":{"description":"Error inesperado durante la creación del envío."}}}}}}
```