Registro de ventas desde Multivende hacia tu sistema

Para registrar las ventas desde Multivende hacia un sistema tenemos a disposición dos herramientas:

• Webhooks: Son notificaciones en tiempo real que se generan cuando ocurre un evento en Multivende y se envían a la aplicación por medio del Callback_URL.
• Polling: Es un proceso de consulta de ventas que funciona como complemento del webhook. 

¿Cómo realizar esta implementación?

Consultar ventas

Se debe consultar las ventas de un rango de fechas cada M (Frecuencia de ejecución) horas, estableciendo lo siguiente:

• from = fecha y hora de la última vez que se ejecutó correctamente el polling (si no se ha ejecutado, desde que fecha y hora se deben consultar las ventas).
• to = la fecha y la hora actual.
• M = frecuencia de ejecución (recomendamos usar M = 1 -2 horas).

Debes utilizar el endpoint Get checkouts light whit scroll para realizar el sondeo de las órdenes desde Multivende.
En cada solicitud, se debe enviar el MerchantId.

De manera opcional, puedes filtrar por MarketplaceConnectionId y obtener las ventas utilizando los campos de fecha:

• UpdatedAt: fecha de última actualización de la orden.
• SoldAt: fecha de venta en el canal de venta.

También debes definir el límite (limit) de resultados a consultar (valor permitido entre 50 y 1000). Este endpoint permite obtener las ventas del merchant paginadas mediante scroll.

Modos de consulta según funcionalidad a integrar

1. Sistemas que intervienen en la operación de la orden. Por ejemplo: generación de etiquetas, documentos tributarios, entre otros.
   1. _updated_at_from (buscar en fecha de última actualización en Multivende).
   2. _updated_at_to (buscar hasta la fecha de última actualización en Multivende).
   3. _marketplace_connection_id (opcional, filtra por Marketplace).
       
2. Sistemas que no intervienen en la operación de la orden. Por ejemplo: reportería, herramientas de BI. 
   1. _sold_at_from (buscar en Fecha de venta en el mercado).
   2. _sold_at_to (buscar hasta la fecha de venta en el Marketplace).
   3. _marketplace_connection_id (opcional, filtra por Marketplace). 

Se pueden consultar las ventas cada M = 1 hora, por ejemplo, pasando en los parámetros a continuación:

_updated_at_from --> "from".
_updated_at_to --> "to".

Estos parámetros tienen el formato y la zona horaria en UTC, puedes utilizar los siguientes formatos: 

• YYYY-MM-DD
• YYYY-MM-DDTHH:mm
• YYYY-MM-DDTHH:mm:ss
• YYYY-MM-DD[T]HH:mm:ss.SSS[Z]

Ejemplo:

Si la fecha actual es “2020-03-18 20:30”, el request sería de la siguiente manera:

curl --location -g '{{base_url}}/api/m/{{merchant_id}}/checkouts/light/limit/{{limit}}?_scroll_id={{scroll_id}}&_updated_at_from=2025-01-01T13:43:00.OOOZ&_updated_at_to=2025-01-02T13:490:00.OOOZ'

--header 'Authorization: Bearer {{access_token}}'

En donde este sería el Response:

{
  "entries": [
    {
      "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "status": "created",
      "verifyStatus": "verificado",
      "paymentStatus": "completado",
      "soldAt": "2019-10-10T16:12:59.000Z",
      "createdAt": "2019-10-10T16:13:01.000Z",
      "updatedAt": "2019-10-31T22:01:09.000Z",
      "BillingAddressId": null,
      "DeliveryTypeId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
  ],
  "pagination": {
    "limit": 50,
    "scroll_id":XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX,
    "previous_id":XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  }
}

Recomendamos registrar en su sistema los campos updatedAt (Fecha de última actualización en Multivende), soldAt (Fecha de la venta en el canal), y "_id" (identificador de la venta en Multivende), ya que con estos campos se puede comparar en sus registros y validar si es una nueva venta o se debe actualizar.

Consultar detalle de venta por "_id"

Una vez se tenga el "_id" de la venta (response anterior), se consulta su detalle con el endpoint Get Checkout.

Campos importantes dentro de la venta:

• Información general de la venta:
  • "_id": identificador de Multivende para la venta.
  • "origin": Nombre del canal desde donde se origina la venta.
  • Fechas:  
    • "soldAt": fecha en que se registró la venta en el canal.
    • "createdAt": fecha en que se registró la venta en Multivende.
    • "updatedAt": fecha en la venta se actualizó por última vez.
  • "courierName": nombre del courier asignado por el canal.
  • "shippingMode": modo logístico que informa el canal.

• "Client" (Información asociada al cliente que realizó la compra):
  • "fullName": Nombre completo.
  • "name": Nombre.
  • "lastName": Apellido
  • "comune": Comuna.
  • "city": Ciudad.
  • "documentType": Tipo de documento.
  • "taxId": RUT o DNI.
  • "email":  Correo electrónico.
  • "phoneNumber" Número telefonico.
• "BillingAddresses" (Dirección de facturación - Se encuentra dentro del "Client")
  • "address_1" - "address_2": Direcciones.
  • "zipCode":  Código Postal.
  • "city":  Ciudad.
  • "country": País.
  • "neighborhood":  Comuna - Barrio.
  • "state": Estado.

• "CheckoutLink" (Trae la información asociada al canal remoto):

  • "externalId": Contiene el "id" del pedido remoto.
  • "externalOrderNumber":   Contiene el número del pedido remoto.
  • "externalCustomerOrderNumber":  Contiene el número del pedido remoto que es visible para el cliente final.
  • "externalContent": Contiene la información JSON del pedido remoto externo, que se toma de la API de integración.
     
  ⚠️ Importante: 
  El campo "externalContent" devuelve la información nativa del canal. Por favor, NO tomes los datos de este campo. 
  
  De ser necesario, comunicarse previamente con el equipo de Integraciones API Multivende.

   

• "CheckoutItems"
  • Información asociada a los productos que se compraron. Devuelve un array por cada item.
    • "CheckoutItems" -> "ProductVersion" -> "code": SKU del item.

• Prices by item: (Estos se encuentran dentro del campo "CheckoutItems")
  • "gross": Precio del artículo (sin descuento).
  • "count": Cantidad solicitada del SKU.
  • "total": Total neto (gross * count).
  • "discount": Descuento aplicado al producto.
  • "totalWithDiscount":Total neto menos descuento (total  - discount)
     

Información asociada a los precios totales de la orden

• "total": Importe Total Bruto (Sin descuentos de venta, incluye descuentos por artículo)
• "totalDiscounts": Cantidad total de descuentos
• "totalWithDiscount": Importe Neto Total (Con descuento)
• "totalPayment": Importe Neto Total (Con descuento + envío)
• "DeliveryOrder" -> "cost": Importe Total Envío del pedido (Flete)

• "CheckoutPayments"
  • Información asociada a los pagos y métodos de pagos de la orden.
    • "CheckoutPayments" -> "PaymentMethod": identificar el o los métodos de pagos.
      • Más información aquí -> ¿Cómo funcionan los medios de pago?
         
• "DeliveryOrdersInCheckouts": Se refiere a la venta con despachos, el cual es un arreglo que detalla toda la información de los despachos de la venta.
  • Cada despacho viene dentro de un objeto que se llama DeliverOrder. En el objeto se encuentra la dirección de despacho dentro del objeto ShippingAddress.

• PickUpOrders: Se refiere a la venta con retiro en tienda, el cual es un arreglo que detalla toda la información del retiro en tienda para la venta.

Importante: 

• Multivende mantiene la misma estructura, pero los datos pueden variar según el canal. Por ejemplo:
• Los campos DeliveryOrdersInCheckouts y PickUpOrders son arrays dado que una venta puede tener más de un despacho o retiro en tienda asociado.
• Una venta puede contener tanto “DeliveryOrdersInCheckouts” (Despachos) como “PickUpOrders” (Retiros en tienda) esto siempre y cuando el canal lo permita.
• Get delivery order types: Tipos de entrega  para una orden.
   

Ejemplos:

1. El campo country puede tener el valor CL o Chile.
2. El campo indication puede llegar el detalle de la calle y casa y en otra venta llegar separado en el campo calle y número.

• Entrega con despacho

Podemos consultar el detalle de la orden para tomar la data relevante para la operación logística mediante el endpoint  delivery order.

• Entrega con retiro en tienda

Podemos consultar el detalle de la orden para tomar la data relevante para la operación logística mediante el endpoint pickup order.

• Entrega Mixta

Se consultan ambos endpoints de acuerdo al tipo de entrega de cada producto.

Consideraciones importantes

• A través de los webhooks las apps resultan más eficientes, porque identifican cuando se produce un cambio en tiempo real y entonces, puede hacer las solicitudes periódicas en un rango de tiempo más amplio a la API para obtener el contenido actualizado.
• Si quieres evitar las actualizaciones masivas que los canales hacen de forma repentina,
  puedes agregar una validación que limite "sold_at" a un rango de 1 a 2 meses.
• Los webhooks se deben complementar con un polling para disminuir la probabilidad de pérdida de datos. (Actualmente no estamos realizando re intentos que aseguren el delivery de la notificación).
• Deben validar siempre desde webhooks y polling que el id de la venta informado ya se encuentre registrado en tu sistema para ver si la creas o actualizas.
• Validar para actualizar si la fecha de updateAt es diferente a la que tienes registrada.
• Para determinar el estado de un despacho, no se debe validar el campo deliveryStatus.
  En su lugar, siempre se debe utilizar el campo deliveryOrderStatusId, ya que este contiene los estados normalizados en Multivende de acuerdo con la información proporcionada por el canal de venta. 
  • Puedes encontrar los estados en el siguiente artículo:
    • Estados de una orden con despacho.
    • Estados de una orden con retiro en tienda.

Ventas con errores:

Es posible consultar los ids de las ventas que no se registraron en Multivende por motivos de error durante el registro, esto puede funcionar como una auditoría. Para realizar la consulta de estos ids pueden realizar un request al endpoint Get checkouts with error

La respuesta de la api dará una descripción del error que causó el no registro correspondiente de la orden. Recordar que cuando la orden es corregida, se lleva a cabo el registro de la misma con un id diferente.

Response: 

{
  "entries": [
    {
      "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "externalId": "XXXXXXX",
      "externalContent": null,
      "error": "StatusCodeError: 404 - {\"cause\":\"\",\"message\":\"Order do not exists\",\"error\":\"order_not_found\",\"status\":404}\n at new StatusCodeError (...)",
      "archived": "disabled",
      "count": 0,
      "status": null,
      "eventStatus": "error",
      "type": null,
      "createdAt": "2021-05-22T04:29:46.000Z",
      "updatedAt": "2021-05-22T04:29:46.000Z",
      "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "MarketplaceConnectionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "CreatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "UpdatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
    },
    {
      "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "externalId": "XXXXXXX",
      "externalContent": null,
      "error": "StatusCodeError: 404 - {\"cause\":\"\",\"message\":\"Order do not exists\",\"error\":\"order_not_found\",\"status\":404}\n at new StatusCodeError (...)",
      "archived": "disabled",
      "count": 0,
      "status": null,
      "eventStatus": "error",
      "type": null,
      "createdAt": "2021-05-22T04:11:37.000Z",
      "updatedAt": "2021-05-22T04:11:37.000Z",
      "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "MarketplaceConnectionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "CreatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "UpdatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
    }
  ]
}

Flujo de la consulta

Equipo Integraciones API Multivende