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.

Recuerda, no se deberían crear envíos en forma directa, si no Ordenes de Marketplace.

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

post

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

/orders

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

Autorizaciones

basicAuthbearerAuth

AuthorizationstringRequerido

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

Cuerpo

application/json

channelstringRequerido

Canal de venta en el formato "marketplace:{code}". Por el momento solo se aceptan canales de tipo marketplace.

Example: marketplace:meli

account_idintegerRequerido

ID de la cuenta vendedora a la que se asociará la órden. El usuario autenticado debe tener acceso a esta cuenta.

Example: 1

external_idstringRequerido

ID de la órden en el sistema del marketplace. Máximo 30 caracteres.

Example: MLA123456789

sourcestring · nullableOpcional

Identificador de origen opcional para rastrear qué integración o sistema envió la órden. Máximo 20 caracteres.

Example: mi-conector

created_atstring · date-timeRequerido

Fecha y hora ISO 8601 de cuando fue creado la órden originalmente en el marketplace.

Example: 2024-01-15T10:00:00-03:00

total_amountnumberRequerido

Monto total de la órden (productos + envío).

Example: 5000

paid_amountnumberRequerido

Monto efectivamente pagado por el comprador.

Example: 5000

shipping_paid_amountnumberRequerido

Costo de envío pagado por el comprador (0 para envío gratuito).

Example: 0

currencystringOpcional

Código de moneda ISO 4217 para los montos de la órden. Por defecto, la moneda del país de la cuenta.

Example: ARS

create_shipmentbooleanOpcional

Cuando es true, se crea automáticamente un envío a partir de la órden de forma sincrónica. Por defecto false.

Example: false

Respuestas

201

Pedido creado exitosamente. Si create_shipment=true, el array shipments estará poblado con el envío generado.

application/json

Representa un pedido de marketplace y sus detalles de envío asociados.

idintegerOpcional

Identificador único del pedido

Example: 12345

account_idintegerOpcional

ID de la cuenta vendedora propietaria del pedido

Example: 1

completed_atstring · date-time · nullableOpcional

Fecha y hora en que el pedido fue marcado como completado (pago confirmado)

Example: 2024-01-15T10:10:00-03:00

shipment_requested_atstring · date-time · nullableOpcional

Fecha y hora en que se solicitó la creación del envío para este pedido

Example: 2024-01-15T10:15:00-03:00

saved_origin_idinteger · nullableOpcional

ID de la dirección del libro de direcciones utilizada como origen del envío

Example: 5

logistic_typestring · nullableOpcional

Código del tipo logístico (ej. cross_docking, fulfillment)

Example: cross_docking

carrier_idinteger · nullableOpcional

ID del transportista asignado a este pedido

Example: 3

service_type_idinteger · nullableOpcional

ID del tipo de servicio asignado a este pedido

Example: 7

destinationone of · nullableOpcional

Dirección de destino de entrega

total_paid_amountnumber · nullableOpcional

Monto total pagado por el comprador

Example: 5000

total_shipping_paid_amountnumber · nullableOpcional

Monto de envío pagado por el comprador

Example: 0

currencystring · nullableOpcional

Código de moneda del pedido (ISO 4217)

Example: ARS

tagsstring[] · nullableOpcional

Etiquetas asociadas al pedido

created_atstring · date-timeOpcional

Fecha y hora en que se creó el registro en Zipnova

Example: 2024-01-15T10:00:00-03:00

updated_atstring · date-timeOpcional

Fecha y hora de la última actualización del registro

Example: 2024-01-15T10:20:00-03:00

400

Tipo de canal inválido o cuenta no encontrada.

401

No autenticado.

403

Permisos insuficientes o sin acceso a la cuenta/marketplace indicado.

422

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

Error inesperado durante la creación del envío.

post/orders

HTTPcURLJavaScriptPython

POST /v2/orders HTTP/1.1
Host: api.zipnova.com.ar
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 775

{
  "channel": "marketplace:meli",
  "account_id": 1,
  "external_id": "MLA123456789",
  "source": "mi-conector",
  "created_at": "2024-01-15T10:00:00-03:00",
  "total_amount": 5000,
  "paid_amount": 5000,
  "shipping_paid_amount": 0,
  "currency": "ARS",
  "create_shipment": false,
  "shipping": {
    "origin_id": 5,
    "carrier_id": 3,
    "logistic_type": "cross_docking",
    "service_type": "standard"
  },
  "delivery": {
    "recipient": {
      "name": "Juan Pérez",
      "document": "20-12345678-9",
      "email": "[e-mail]",
      "phone": "1145678901"
    },
    "point_id": 123,
    "address": {
      "street": "Av. Corrientes",
      "street_number": "1234",
      "street_extras": "Piso 3, Dpto B",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "zipcode": "C1043"
    }
  },
  "items": [
    {
      "sku": "SKU-001",
      "name": "Producto A",
      "qty": 1,
      "unit_price": 5000,
      "currency": "ARS",
      "weight": 500,
      "height": 10,
      "width": 10,
      "length": 15
    }
  ]
}

{
  "id": 12345,
  "account_id": 1,
  "channel": {
    "type": "marketplace",
    "marketplace": "meli",
    "created_at": "2024-01-15T10:00:00-03:00",
    "paid_at": "2024-01-15T10:05:00-03:00",
    "data": {}
  },
  "completed_at": "2024-01-15T10:10:00-03:00",
  "shipment_requested_at": "2024-01-15T10:15:00-03:00",
  "saved_origin_id": 5,
  "logistic_type": "cross_docking",
  "carrier_id": 3,
  "service_type_id": 7,
  "destination": {
    "id": 2971,
    "name": "Zipnova - Garín",
    "street": "Tierra del Fuego",
    "street_number": "2498",
    "street_extras": "Nave 3 - GoodPark",
    "zipcode": "1619",
    "phone": "[phone]",
    "email": "[e-mail]",
    "document": "30-70835592-1",
    "city": {
      "id": 815,
      "name": "Garín"
    },
    "state": {
      "id": "AR-B",
      "name": "Buenos Aires"
    },
    "country": {
      "id": "AR",
      "name": "Argentina"
    },
    "location_latitude": -34.4250302,
    "location_longitude": -58.7320621,
    "location_type": null,
    "location_metadata": null,
    "is_accurate": null,
    "created_at": "2020-12-01T18:31:01.000000Z",
    "updated_at": "2020-12-01T18:31:01.000000Z",
    "confirmed_at": null
  },
  "items": [
    {
      "id": 1001,
      "qty": 2,
      "unit_price": 2500,
      "currency": "ARS",
      "product_id": 88,
      "data": {
        "sku": "SKU-001",
        "name": "Producto A"
      }
    }
  ],
  "total_paid_amount": 5000,
  "total_shipping_paid_amount": 0,
  "currency": "ARS",
  "tags": [
    "text"
  ],
  "shipments": [
    {
      "id": 9001,
      "external_id": "OCA-000123",
      "tracking_id": "ZP-9001",
      "status": "ready_to_ship",
      "tracking_url": "https://track.zipnova.com.ar/ZP-9001"
    }
  ],
  "created_at": "2024-01-15T10:00:00-03:00",
  "updated_at": "2024-01-15T10:20:00-03:00"
}