Saltar al contenido principal

Carga de ventas de canales via API: Tutorial Completo

Actualización

Luego de completar la configuración de la relación entre las plataformas y publicado los productos, se podrán registrar nuevas órdenes vía API si cuenta con los permisos necesarios para administrar las ventas de la conexión realizada.

Para poder registrar una venta se deben cumplir las siguientes condiciones:

  1. El producto debe estar registrado en Multivende.
  2. Los "id" deben ser únicos por conexión.
  3. Validar antes al momento de realizar el pago de la orden el stock.

 

A continuación, se detalla los campos que deben enviar a través del endpoint Created checkout

Detalles de los campos a enviar para crear una venta:

  • "id": Identificador único de la orden en el canal. 
  • "orderNumber": Número de orden entregado al Merchant.
  • "customerOrderNumber": Número de orden entregado al cliente.
  • "externalCreatedAt": Fecha de creación de la orden en el canal (Ver formato valido).
  • "externalUpdatedAt": Fecha de última actualización de la orden en el canal (Ver formato valido).
  • "soldAt": Fecha de venta (Ver formato valido).
  • "currencyCode": Moneda en la cual se realizó la venta (Ver valores validos).
  • "comment": Comentarios de la orden. (Opcional).
  • "net": Precio de venta total sin impuestos, descuentos y costo de envío. (Opcional).
  • "tax": Impuestos. (Opcional).
  • "total": Precio de venta total con impuestos, sin descuentos y sin costo de envío.
  •  "discounts": Array de descuentos aplicados a la venta, no se deben incluir los descuentos por item. (Opcional).
    • "detail": Detalles del descuento.
    • "discount": Valor del descuento.
    • "discountType": Tipo de descuento (Ver valores validos).
  • “externalContent”: JSON en formato string del detalle de la orden en el canal.
  • "client":
    • "id": Identificador único del cliente en el canal.
    • "documentType": Tipo de documento. (Opcional).
    • "taxId": Número de identificación nacional (Rut, pasaporte, DNI, etc).
    • "name".
    • "lastName".
    • "contactName".
    • "activity": Actividad a la que se dedica (Rubro, etc). (Opcional).
    • "birthday": Fecha de cumpleaños. (Opcional).
    • "email". (Opcional).
    • "phoneNumber". (Opcional).
    • "type": Tipo de cliente (Ver valores validos).
  • "billingClient": 
    • "name": "company or client name",
    • "taxName": "company name",
    • "taxActivity": "company activity",
    • "taxId": "document number",
    • "documentType": "document type",
    • "legalRepresentative": "legalRepresentative name",
    • "legalRepresentativeTaxId": "999999999",
    • "email": "email@mail.cl",
    • "phoneNumber": "5555555555",
    • "type": "company or person",
    • "billingAddress": 
      • "name":"company name",
      • "address_1": "address_1",
      • "address_2": "address_2",
      • "indications": "indications",
      • "description": "description",
      • "importance": "principal" 
  • "checkoutItems": Array dónde se debe enviar los ítems de la venta con el precio de venta.
        • "sku": sku del productVersion.
        • "quantity": cantidad total de ítems en la venta.
        • "unitPrice": Precio de venta total del item con impuestos, sin descuentos y sin costo de envío.
        • "net": Precio total del item sin impuestos, descuentos y costo de envío. (Opcional).
        • "tax": Impuestos. (Opcional).
        •  "discounts": Array de descuentos aplicados al item, este descuento no se debe incluir en el array de discounts de la venta.
          • "detail": Detalles del descuento.
          • "discount": Valor del descuento.
          • "discountType": Tipo de descuento (Ver valores validos).
 
  • "deliveryOrders": Array de las diferentes entregas a domicilio de una orden. En el caso que la orden no tenga despacho a domicilio se debe enviar el array vacio.
    • "id": Identificador único de la orden de despacho en el canal.
    • "externalContent": JSON en formato string del detalle de la orden de despacho en el canal.
    • "createdAt": Fecha de creación de la orden de despacho en el canal (Ver formato valido).
    • "updatedAt": Fecha de última actualización de la orden de despacho en el canal (Ver formato valido).
    • "shippingMode": Modalidad Logística. (Opcional).
    • "courierName": Nombre del courier. (Opcional).
    • "trackingNumber": Número de tracking del courier. (Opcional).
    • "trackingContent": Detalles del tracking. (Opcional).
    • "cost": Costo del despacho con impuestos.
    • "estimatedDeliveryDateFrom": Fecha inicial del rango de entrega (Ver formato valido).
    • "estimatedDeliveryDateTo": Fecha límite para entrega (Ver formato valido).
    • "effectiveDeliveryClosingDate": Fecha en que se entregó la orden de despacho (Ver formato valido, opcional).
    • "promisedDeliveryDate": Fecha de promesa de entrega al cliente (Ver formato valido).
    • "handlingDateLimit": Fecha límite de entrega al Courier (Ver formato valido).
    • "comment": Comentarios para la orden de despacho. (Opcional).
    • "deliveryOrderStatus": Estado de la orden de despacho, se detalla más adelante los valores permitidos (Ver valores permitidos).
    • "shippingAddress": Dirección donde se debe despachar la orden.
      • "address_1": Dirección.
      • "address_2": Dirección. (Opcional).
      • "neighborhood": Comuna.
      • "number": Numeración de la calle.
      • "street": Calle.
      • "country": País.
      • "state": Región.
      • "city": Ciudad.
      • "zipCode":  Código postal. 
      • "description": (Opcional).
      • "indications": Indicaciones para ubicar la dirección. (Opcional).
    • "shippingAddressReceiver": Datos de la persona que recibirá la orden de despacho.
      • "documentType": Tipo de documento. (Opcional).
      • "taxId": Número de identificación nacional (Rut, pasaporte, DNI, etc). (Opcional).
      • "name".
      • "lastName".
      • "contactName”.
      • "email”. (Opcional).
      • "phoneNumber". (Opcional).
    • "deliveryOrderItems": Array de ítems que se van a entregar en la orden de despacho indicando la cantidad y bodega donde se va a descontar el stock.
      • "sku": sku del productVersion.
      • "quantity": Cantidad de ítems a descontar de la bodega indicada.
      • "fulfilledWarehouseId": Id de la bodega donde se descontará el stock, este Id se obtiene de la configuración inicial para el mapeo de las bodegas. 
  • "pickUpOrders": Array de las diferentes entregas con retiro. En caso que la orden no tenga retiro en tienda se debe enviar el array vacio.
    • "id": Identificador único de la orden de retiro en el canal.
    • "externalContent": JSON en formato string del detalle de la orden de retiro en el canal.
    • "createdAt": Fecha de creación de la orden de retiro en el canal.
    • "updatedAt": Fecha de última actualización de la orden de retiro en el canal.
    • "cost": Costo por retiro con impuestos. 
    • "estimatedPickUpDateFrom": Fecha inicial del rango de retiro (Ver formato valido).
    • "estimatedPickUpDateTo": Fecha límite para el retiro (Ver formato valido).
    • "effectivePickUpClosingDate": Fecha en que se entregó la orden de retiro. (Ver formato valido, opcional).
    • "comment": Comentarios para la orden de retiro. (Opcional).
    • "pickUpOrderStatus": Estado de la orden de retiro, se detalla más adelante los valores permitidos (Ver valores validos).
    • "warehouseId": Id de la tienda en Multivende donde se va a retirar la orden.
    • "pickUpOrderPicker": Datos de la persona que retirará la orden de retiro.
      • "documentType": Tipo de documento. (Opcional).
      • "taxId": Número de identificación nacional (Rut, pasaporte, DNI, etc). (Opcional).
      • "name".
      • "lastName".
      • "contactName”.
      • "email”. (Opcional).
      • "phoneNumber". (Opcional).
    • "pickUpOrderItems": Array de ítems que se van a entregar en la orden de retiro indicando la cantidad y bodega donde se va a descontar el stock.
      • "sku": sku del productVersion.
      • "quantity": Cantidad de ítems a descontar de la bodega indicada.
      • "fulfilledWarehouseId": Id de la bodega donde se descontará el stock, este Id se obtiene de la configuración inicial para el mapeo de las bodegas. 
  • "checkoutPayments": Array con los pagos registrados en la orden.
    • "id": Identificador único del pago en el canal.
    • "transactionId": Número de transacción.
    • "code": Código de transacción. (Opcional).
    • "paymentStatus": Estado del pago (Ver valores validos).
    • "datePaid": Fecha de pago (Ver formato valido).
    • "amountPaid": Monto pagado.
    • "installments": Cantidad de cuotas. (Opcional).
    • "cardNumber": Número de tarjeta. (Opcional).
    • "authorizationCode": Código de autorización.
    • "detail": Detalles del pago. (Opcional).
    • "verificationStatus": Estado de verificación del pago (Ver valores permitidos).
    • "dateVerificated": Fecha cuando se verificó el pago (Ver formato valido).
    • "externalContent": JSON en formato string del detalle del pago en el canal.
    • "paymentMethodCode": Código del método de pago registrado en el mapeo inicial de configuración, se detalla más adelante los valores permitidos (Ver valores permitidos).

 

A continuación, te detallamos los valores válidos para los campos

Global

  • Formato para las fechas, todas nuestras fechas se encuentran almacenadas en formato UTC, por lo que se debe enviar las fechas siguiendo este formato “YYYY-MM-DDThh:mm:ss.sTZD”. Donde:
    • YYYY = un año de cuatro dígitos
    • MM = un mes de dos dígitos, de 01 a 12
    • DD = un día del mes de dos dígitos, de 01 a 31
    • T = un valor literal que sigue a la fecha y presenta la hora
    • hh = dos dígitos para la hora, de 00 a 23
    • mm = dos dígitos para los minutos, de 00 a 59
    • ss = dos dígitos para los segundos, de 00 a 59
    • s = uno o varios dígitos que representan una fracción decimal de un segundo
    • TZD = designador de zona horaria (Z o +hh:mm o -hh:mm)
      • Z para hora UTC
      • +hh:mm para una zona horaria local anterior a UTC
      • -hh:mm para una zona horaria local posterior a UTC

  • “currencyCode”: se debe enviar el campo “code” del mapeo realizado en la configuración inicial para la moneda a través del endpoint Get currencies

  • “verificationStatus": 
    • 'verified': Todos los pagos de la orden están verificados.
    • 'pending': Todos o algunos de los pagos aún no están verificados.
  • “paymentStatus": 
    • 'completed': Todos los pagos de la orden esta completos, cubriendo el total del valor de los ítems y el despacho.
    • 'pending': Hay por lo menos un pago pendiente para se cubra el total del valor de los ítems y el despacho.
    • 'rejected': Todos los pagos fueron rechazados.
    • 'refunded': Se solicita devolución de todos los pagos. 
  • “deliveryStatus": 
    • 'canceled': Se canceló la orden.
    • 'delivered': Se completaron todas las entregas de la orden.
    • 'not-delivered': No se entregó una de las entregas de la orden.
    • 'pending': Pendiente de por lo menos una de las entregas de la orden.

"discounts"

  • "discountType":
    • "value": Si el descuento es un monto especifico.
    • "percentage": Si el descuento aplicado es un porcentaje del valor.

“client”

  • “type”:
    • ‘person’: Persona.
    • ‘company’: Empresa.

“deliveryOrders”

  • “status”:
    • “pending”: La orden de despacho se creó y está pendiente de preparación.
    • “under_review”: La orden de despacho está en revisión para ser despachada.
    • “handling”: La orden de despacho fue tomada para preparación.
    • “ready_to_ship”: La orden de despacho esta lista para ser despachada.
    • “shipped”: La orden de despacho fue enviada.
    • “delivered”: La orden de despacho fue entregada.
    • “not_delivered”: La orden de despacho no fue entregada.
    • “cancelled”: La orden de despacho fue cancelada.
    • “reschedule”: La orden de despacho se reprogramó. 

 “pickUpOrders”

  • “status”:
    • “pending”: La orden de retiro en tienda se creó y está pendiente de preparación.
    • “handling”: La orden de retiro en tienda fue tomada para preparación.
    • “received_by_store”: La orden de retiro en tienda fue recibida por la tienda.
    • “completed”: La orden de retiro en tienda fue entregada.
    • “cancelled”: La orden de retiro en tienda fue cancelada.

 “checkoutPayments”

  • “paymentStatus":
    • 'completed': El pago fue completado.
    • 'pending': El pago está pendiente.
    • 'rejected': El pago fue rechazado.
    • 'refunded': 
    • 'cancelled': El pago fue cancelado.
  • “verificationStatus":
    • 'verified': El pago está verificado.
    • 'pending': El pago está pendiente de verificación.
  • “paymentMethodCode”: Se debe enviar el campo “code” del mapeo realizado en la configuración inicial para los métodos de pago a través del endpoint Get checkout payment methods

 

Si tienes dudas sobre este tema contáctanos a través de api@multivende.com y estaremos felices de ayudarte.

Equipo Integraciones API Multivende

 

Artículos relacionados