Saltar al contenido principal

Registro de ventas desde Multivende: Instrucciones para integrarlas en tu sistema

Actualización

 

Conoce las herramientas que tenemos disponibles en Multivende para que puedas registrar tus ventas desde la plataforma hacia tu sistema

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

  1. 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.
  2. 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).

Recomendamos usar el endpoint Get checkouts light para realizar el sondeo de las órdenes desde Multivende.

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. _sold_at_order (opcional, ordenar ASC o DESC).
    4. _marketplace_connection_id (opcional, filtra por Marketplace).

Importante: Ésta opción no es recomendada para sistemas del punto 1, ya que puede haber desfase de fechas y horas en las que el marketplace y Multivende registraron la venta.

Se pueden consultar las ventas cada M = 1, 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, es decir: "YYYY-mm-dd hh:mm:ss".

Ejemplo:

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

curl --location --request GET

'http://app.multivende.com/api/m/b4bbbbbb-fff2-45b1-99989-0afc7xx32xxx/checkouts/light/p/1?_updated_at_from=2020-03-18 18: 30 & _updated_at_to = 2020-03-18 20:30 '\

--header' Autorización: Baerer eyJ0eXAiOiJKV1QiLCJhbGcixxxxxxxxxxxJ9.e ………… .. '

En donde este sería el Response:

{
"entries": [
{
   "_id": "XXXXXXXX-XXXX-XXXX-b7b6-ad9exxx06906",
   "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 ":" 9474c2a8-6a0c-11e6-9651-70928b05753b ",
   " MerchantId ":" bf03e4e6-53a0-4082-9476-643633009049 "
}, 
{
   " _id ":"hasud4c1-2255 -ad9exxx06906 ",……………………………………… ..
},
………………………………………………… ..
],
   " paginación ": {
        "desplazamiento": 0,
        "limit": 50,
        "total_pages": 1,
        "current_page": 1,
        "next_page": 0,
        "previous_page": 0,
        "total_items": 11
  }
}

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, 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 el detalle con el endpoint Get Checkout cuando el response tiene el campo:

  • 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.

Importante: 

  • Multivende mantiene la misma estructura, pero los datos pueden variar según el canal. Por ejemplo:
  • Ese campo es un Array dado que una venta puede tener más de un despacho o retiro en tienda asociado.

  • Una venta puede contener tanto “DeliveryOrder” (Despacho) como “PickUp” (Retiro) 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 Get 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 Get 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.
  • 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).
  • Si al consultar el detalle de la venta con el CheckoutId el response es con status 404, se debe a que se trata de una venta que presentó error en el registro de Multivende la cual no queda registrada.
  • 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.

Consideraciones importantes - Paris Marketplace

  • El tiempo para completar una orden informada desde Paris puede variar y en algunos casos requerir una espera adicional para completar en su totalidad; Debido a la manera en que funciona Paris, el canal puede ir informando despachos(sub-órdenes) asociadas a una venta un tiempo después de recibida la venta.
  • ¿Cómo identificamos esto?

    • Mediante  el parámetro .tags = 'order_externally_updated' se puede identificar cuando una orden de Paris ha sido actualizada y se han agregado más items y nuevos despachos. 

Importante: cuando se informe "tags" = 'order_externally_updated', deben validar los campos "CheckoutItems" y "DeliveryOrderInCheckouts" para que estos nuevos despachos los cuales contienes nuevos items (sub-ordenes) sean agregadas a su sistema.

 

Flujo de la consulta

 

Si tienes dudas, escribe a api@multivende y te ayudaremos.

Equipo Multivende

 

Artículos relacionados