Integraciones API

Conéctate vía API a una o más cuentas de Merchant y automatiza operaciones con nuestra API Rest.

Flujo global de integraciones

Multivende actúa como el centro de gestión para el catálogo de productos de un usuario, como observamos en el diagrama más abajo. (Diagrama flujo global de integraciones)

En este artículo te presentamos los pasos que debes seguir para integrar una aplicación.

Para poder integrar una aplicación deberás:

1. Crear tu cuenta de desarrollador, si no cuentas con una debe ser creada con un correo que no esté registrado en Multivende.
2. Crear tu aplicación en nuestra plataforma.
    

   Vídeo del proceso

    
3. Desarrollar la conexión entre Multivende y la aplicación y la interfaz por la cual el Merchant realizará la configuración de la comunicación, esta comunicación se realizará por medio de Oauth2.
4. Si la aplicación es un Marketplace, lee las siguientes consideraciones.
5. Obtener detalles de la conexión entre tu APP y la cuenta del Merchant Get app information.
6. ¡Listo! Puedes empezar a consultar nuestra API y realizar la integración con Multivende.

Consideraciones Generales:

1. La aplicación debe cumplir con los estándares de seguridad definidos en el siguiente artículo.

2. Nuestras fechas están en formato UTC, se debe realizar la conversión según la zona horaria.
3. Los datos enviados a la aplicación deben ser almacenados en su base de datos y por medio de los webhooks se notificarán los cambios para que puedan ser actualizados, por lo que no se debe realizar consultas constantes para obtener la información de algún recurso.
4. El desarrollo debe considerar reintentos en caso de error.
5. Una aplicación se puede relacionar a más de un Merchant.
6. Un Merchant puede tener múltiples conexiones a la misma aplicación.
7. No puedes tener la sesión de la cuenta desarrollador y merchant en el mismo navegador.

Consideraciones Partners:

1. La integración debe ser estándar para que los Merchant puedan configurar rápidamente la relación entre los sistemas.
2. Se debe generar un manual de integración que será publicado en nuestro Help Center. El cual debe contener:
   1. ¿Cómo contactarse con el área comercial para contratar el servicio?.
   2. ¿Cómo contactarse con soporte en caso de tener algún inconveniente?.
   3. Condiciones del servicio.
   4. Funcionalidades que realiza la integración.
   5. Flujo que debe realizar para habilitar la integración, con capturas de pantalla que respalden la acción indicada.
3. Más información en el siguiente artículo recomendaciones para partners.

Equipo Integraciones API Multivende

Para usar la API de Multivende, gestiona tus aplicaciones desde la cuenta de desarrollador.

Debes registrar la app en tu cuenta de desarrollador para integrarla vía API con otro sistema.

A continuación, te mostramos los pasos para crear la aplicación en Multivende:

1. Ingresa al menú de aplicaciones, donde se mostrarán todas tus aplicaciones creadas en Multivende y presiona el botón Crear.

2. Ingresa los datos de tu aplicación.

• Nombre: Nombre de tu aplicación para reconocerla en tu listado de aplicaciones.
• Código: Código para asociar la aplicación. Debe ser único en todo el sistema, por lo que debes seguir la nomenclatura “empresa_nombredelsistema_pais_version”.
• Nombre público: Nombre que se muestra a los merchants en su listado de aplicaciones. Debe ser único en todo el sistema, por lo que debes seguir la nomenclatura “Empresa + nombre del sistema + país + versión”.
• Visibilidad: 
  • Público: Se listará tu aplicación para que los merchants puedan seleccionar tu app y asociarla a su cuenta.
  • Privado: No se listará en el pull de aplicaciones disponibles para integrar.
• URL de destino: Página a la que enviaremos a los merchant para que se realicen el OAuth2.
• URL de marketing: Página donde se mostrará tu publicidad.
• Descripción.
• Descripción pública: Debes detallar las funcionalidades que tiene tu integración, quedará disponible para que el merchant pueda visualizarla.
• Scopes: Permisos que debe otorgar el merchant para que la aplicación funcione correctamente. Puedes encontrar más detalles en el artículo dedicado a los scopes.
• Redirect URL: URL a la que redireccionaremos luego de que el merchant otorgue los permisos necesarios.
• Webhooks: Notificaciones a las que debe estar suscrita la aplicación para que funcione correctamente. Puedes encontrar más detalles en el artículo de webhooks.
• Callback URL: URL a la que enviaremos el POST de la notificación.

3. Carga el logo de tu aplicación. Recuerda que esta debe cumplir con el formato de 45x45 px.

4. ¡Listo! Tu aplicación se ha creado con éxito.

Equipo Integraciones API Multivende

Conoce más sobre nuestra API y accede a su documentación disponible en Postman en este artículo.

Multivende Integration Services (MIS) permite a los clientes o aplicaciones de terceros interactuar con la información del usuario de forma estándar, así como diferentes aspectos de la cuenta de los usuarios.

Puedes comenzar a probar la integración usando una cuenta con la URL base (Base URL) que apunte a la siguiente dirección:

https://app.multivende.com

Recuerda que nuestra comunicación utiliza HTTPS solo con TLS>= 1.2

En el siguiente enlace, podrás consultar el detalle de nuestra API, la cual se encuentra documentada en Postman para que puedas descargar la colección y realizar pruebas a través de la herramienta..

Equipo Integraciones API Multivende

Prueba Multivende creando una cuenta gratuita y conoce sus funciones antes de usarla en tu negocio.

Paso 1: Accede al Sitio Web de Multivende

1. Visita el sitio web oficial de Multivende: www.multivende.com.
2. En la página principal, busca la opción que dice "Crear Cuenta". Podrás encontrar esta opción en la parte inferior de la página.

Paso 2: Completa el Formulario de Registro

1. Rellena tus datos personales: Para crear una cuenta de prueba, deberás proporcionar algunos datos básicos, tales como:

   • Nombre de usuario: 
   • Dirección de correo electrónico (asegúrate de usar una válida)
   • Contraseña segura.
     • Requisitos para la contraseña:
       • Mínimo 12 caracteres.
       • Mínimo 1 letra mayúscula y 1 letra minúscula.
       • Mínimo 1 número.
       • Mínimo 1 símbolo.
       • No puede contener el nombre de usuario.
   • Nombre de la empresa. (Utilizar la siguiente nomenclatura "nombreEmpresa_test")
   • Selecciona tu actividad principal. (Retail, venta mayorista, etc...)
   • Selecciona tu país.
   • Número de telefono. (No olvides incluir el código de area)

2. Completa el reCAPTCHA.

3. Enviar el formulario: Haz clic en el botón "Crear Cuenta".

Paso 3: Inicia Sesión en tu Cuenta

1. Una vez verificada tu cuenta, regresa al sitio de Multivende.
2. En la parte superior derecha, haz clic en "Acceder".
3. Ingresa tu correo electrónico y la contraseña que usaste durante el registro.

Paso 4: Explora las Funcionalidades

Con tu cuenta de prueba ya activa, podrás explorar todas las características que Multivende ofrece, como:

• Crear productos.
• Crear bodegas.
• Cargar stock.
• Cargar precios.
• Crear ventas.
• Administrar inventarios.
• Probar opciones de pago y envío.
• Entre otras...

¿Te gustaría aprender más sobre cómo sacar el máximo provecho a tu cuenta de prueba?
Te invitamos a visualizar nuestro Workshop del Funcionamiento de la plataforma, donde te explicaremos detalladamente cómo utilizar cada funcionalidad y resolveremos todas tus dudas.

Paso 5: Contacta Soporte si tienes preguntas

Si tienes algún problema durante el registro o necesitas asistencia adicional, puedes contactar con el equipo de soporte de Multivende a través de las opciones de ayuda en línea o contacto que se encuentran en el sitio.

Si necesitas más detalles de como contactar al equipo de Integraciones API, puedes ver más detalles en el siguiente artículo:

• ¿Cómo crear un ticket para contactar al Equipo de Integraciones vía API?

Equipo Integraciones API Multivende

Notificaciones en tiempo real de eventos en Multivende enviadas a tu app vía Callback URL.

{
   "CheckoutId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "MerchantId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "MarketplaceConnectionId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "MerchantAppId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "OauthClient":{
      "_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "client_id":"99631xxxxxxx"
   },
   "resource":"checkouts",
   "attemps":1,
   "received":"2021-04-08T19:55:07.061Z"
}

Permisos que otorga el Merchant para que la app acceda solo a los datos de los scopes autorizados.

{
  "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "status": "created",
  "OauthClientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantAppId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "CreatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "UpdatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "OwnerId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "scopes": {
    "read:stocks": {
      "all": true
    }
  },
  "expiresAt": "2024-10-15T19:57:26.468Z",
  "refreshToken": "rt-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "refreshTokenExpiresAt": "2024-10-17T13:57:26.468Z",
  "updatedAt": "2024-10-15T13:57:26.000Z",
  "createdAt": "2024-10-15T13:57:26.000Z",
  "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXX........."
}

{
  "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "status": "created",
  "OauthClientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantAppId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "CreatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "UpdatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "OwnerId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "scopes": {
    "read:stocks": {
      "all": false,
      "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": false,
      "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX1234": true // Bodega con acceso
    }
  },
  "expiresAt": "2024-10-15T19:57:26.468Z",
  "refreshToken": "rt-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "refreshTokenExpiresAt": "2024-10-17T13:57:26.468Z",
  "updatedAt": "2024-10-15T13:57:26.000Z",
  "createdAt": "2024-10-15T13:57:26.000Z",
  "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXX........."
}

{
  "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "status": "created",
  "OauthClientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "MerchantAppId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "CreatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "UpdatedById": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "OwnerId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "scopes": {
    "read:stocks": {
      "all": false // Ninguna bodega con acceso.
    }
  },
  "expiresAt": "2024-10-15T19:57:26.468Z",
  "refreshToken": "rt-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "refreshTokenExpiresAt": "2024-10-17T13:57:26.468Z",
  "updatedAt": "2024-10-15T13:57:26.000Z",
  "createdAt": "2024-10-15T13:57:26.000Z",
  "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXX........."
}

Guía para generar el código de autorización OAuth2 sin necesidad de una interfaz gráfica.

En caso de no contar con una interfaz gráfica para realizar la conexión de la aplicación con la cuenta del Merchant igualmente puede generar tu código de autorización, primero debes ingresar a tu cuenta de Desarrollador, dirigirte a "Aplicaciones", luego a "Listado de aplicaciones" y hacer clic en la acción del "Lápiz" (Editar).

Dentro de la configuración de la aplicación podrás visualizar la opción “Agregar cuentas de merchant”, la cual se encuentra debajo de “Visibilidad”.

Importante, esto solo se puede realizar una vez tengas tu aplicación autorizada.

Una vez dentro, debes insertar el MerchantId en el recuadro y hacer click sobre el botón guardar.

Ahora el Merchant podrá visualizar tu aplicación en el listado de aplicaciones de la vista de Merchants.

Para esto, el Merchant debe ingresar a la plataforma, dirigirse a "Aplicaciones" luego a "Listado de aplicaciones".

Aquí veremos un listado de aplicaciones certificadas de Multivende, se debe hacer scroll hasta el final de la página en donde dice "Listado de aplicaciones propias no certificadas", debes hacer clic en "Ver más" en la aplicación a la cual se desea generar el authorization code, donde el Mrechant podrá otorgar los permisos según lo requiera.

Seguido a esto se debe seleccionar la opción "Generar authorization code", aquí el Merchant podrá brindarle permiso (Scopes) a los datos seleccionados y establecer un nombre para la conexión con la aplicación.

Válida que la información esté correcta y listo, el código de autorización será generado y podrás continuar con el proceso de autenticación mediante Oauth2

Podrás ver el proceso en el siguiente video:

Guía para generar el código de autorización OAuth2 sin reconectar la aplicación.

Para generar un nuevo código de autorización de una aplicación ya conectada a la cual se le expiró el refreshToken o algún problema similar; lo puedes realizar sin generar una nueva conexión de la aplicación en Multivende. Para ello debes seguir los siguientes pasos.

Primero, el Merchant debe ingresar a la plataforma de Multivende, seguido a esto hará clic a la opción "Aplicaciones" la cual desplegará "Listado de aplicaciones".

Aquí el Merchant podrá ver todas las aplicaciones que tenga conectadas en su cuenta:

• Se debe hacer click sobre la acción del lápiz en la aplicación en concreto.

• Luego "Generar código de autorización" 

• Y listo, se ha generado el código de autorización para continuar con tu flujo de autenticación.

Puedes ver los detalles en el siguiente vídeo:

Importante

• El código de autorización solo se genera al principio del flujo, luego debes renovar tu token con el refreshToken. Solo en los casos que el refreshToken expire u algún problema similar, se puede realizar este proceso.
• La obtención del código de autorización es un proceso manual que se realiza únicamente desde la cuenta del Merchant. Este proceso no puede ser automatizado debido a que requiere confirmación por parte del Merchant los permisos a otorgar a la aplicación.

Equipo Integraciones API Multivende

Clave para asegurar que apps externas interactúen de forma segura con una API.

El proceso de autenticación mediante OAuth2 es un paso crucial para garantizar que las aplicaciones de terceros puedan interactuar de manera segura con una API, garantizando que solo los usuarios autorizados puedan acceder a ciertos recursos. Sin embargo, en este proceso, pueden surgir varios errores que impiden obtener o renovar el token de acceso. A continuación, te explicamos los pasos involucrados en este proceso, los posibles errores que podrías enfrentar y cómo solucionarlos.

Proceso de autenticación con OAuth2

Cuando un merchant entrega el código de autorización, se inicia el proceso de autenticación mediante OAuth2. El primer paso consiste en enviar los parámetros necesarios al Endpoint Authenticate OAuth2 utilizando una solicitud HTTP POST.

Ejemplo de solicitud:

En este punto, la API responderá con un objeto que contiene el token, refreshToken y la duración de su validez.

Respuesta exitosa:

El token tiene una validez de 6 horas, mientras que el refreshToken tiene una validez de 48 horas y puede ser utilizado una única vez para renovar el acceso.

Renovación del Token mediante el Refresh Token

Cuando el token está cerca de expirar, se debe utilizar el Endpoint Refresh Token OAuth2 para obtener un nuevo token y un nuevo refreshToken. Esto debe realizarse antes de que el token original caduque, idealmente cuando queda aproximadamente 1 hora de vida.

Ejemplo de solicitud para renovar el token:

Respuesta exitosa:

Este proceso puede ser automatizado para que, cuando el token esté cerca de su expiración (por ejemplo, con 5 horas de antelación), se realice la renovación automática utilizando el refreshToken. De este modo, se garantiza la continuidad en el flujo de autenticación sin interrupciones.

Errores Comunes

1. Token Expirado o Invalidado: Si el token ha expirado y no se ha renovado a tiempo, el proceso debe reiniciarse desde el principio. Esto implica que el merchant deberá generar un nuevo código de autorización manualmente desde la configuración de la aplicación.

2. Refresh Token Expirado o No Utilizado: Si el refreshToken ha expirado o no ha sido utilizado dentro de su período de validez, el proceso también debe reiniciarse desde cero, lo que requerirá que el merchant obtenga un nuevo código de autorización manualmente.

3. Error en la Solicitud de Renovación: Si hay errores en la solicitud de renovación del token (por ejemplo, errores de red, parámetros incorrectos, etc.), asegúrate de validar los datos enviados, como el client_id, client_secret y el refresh_token.

4. Error en la Respuesta del Servidor: Si la API devuelve un error, revisa el código de estado HTTP y el mensaje de error para identificar la causa. Algunos errores comunes incluyen falta de permisos o problemas de autenticación.

Resumen

Para gestionar adecuadamente la autenticación OAuth2, es importante realizar lo siguiente:

• Obtener y gestionar el token y el refreshToken de manera eficiente.

• Automatizar la renovación del token antes de su expiración.

• Asegurarse de que el refreshToken se use dentro de su período de validez.

• Si el refreshToken expira o no es válido, reiniciar el proceso de autenticación obteniendo un nuevo código de autorización manualmente.

Este proceso garantiza que las interacciones con la API sean seguras y fluidas, manteniendo el acceso autorizado de manera continua y sin interrupciones.

Equipo Integraciones API Multivende

Conoce el proceso para interactuar de forma correcta con la API de Multivende para integrar ERP's

Para realizar tu interacción de forma correcta con la plataforma y permitir que tu integración ERP pueda sacar el máximo provecho de las herramientas que brindamos, es necesario iniciar aprendiendo información básica sobre nuestra API, para eso te pedimos leer 5 artículos básicos sobre la integración:

Artículo 1 - Todo lo que debes saber sobre Integraciones API(Requerido)

Detallamos cuáles son los pasos para que tu aplicación pueda conectarse a la cuenta del merchant y poder empezar a consultar sus datos.

Artículo 2 - API Multivende - Postman(Requerido)

Conocerás más sobre nuestra API y su documentación en Postman.

Artículo 3 - Requisitos técnicos generales (Requerido):

Encontrarás la información asociada a las consideraciones técnicas que debes tener en cuenta para la integración.

Artículo 4 - ¿Cómo cargar stock vía API?(Requerido)

Encontrarás la información para realizar la sincronización de stock a Multivende. Para hacerlo, debes hacer uso de los endpoints de la sección “stock”, te recomendamos dejar un cron que sincronice los stocks por lo menos una vez al día. Además de una opción para que el usuario pueda ejecutar el proceso manualmente.

Artículo 5 - Actualización de Precios(Opcional)

Podrás obtener la información para realizar la sincronización de precios a Multivende. Para hacerlo, debes hacer uso de los endpoints de la sección “prices”.

Artículo 3 - ¿Cómo crear productos desde tu sistema a Multivende?(Opcional)

Con información básica (SKUs, Nombre, Variantes)(Recomendado): Te dejamos los endpoint disponibles:

• Get products with scroll: Enumera los productos asociados al Merchant.
• Get product by id: Muestra los detalles de un producto por la ID.

Artículo 4 - Registro de ventas desde Multivende: Instrucciones para integrarlas en tu sistema(Requerido)

Conocerás cómo obtener las ventas e iniciar el proceso de logística. Este es un flujo complementario a los webhooks para repasar las ventas en un rango de fechas y horas dadas, se recomienda:

• Registrar el _id de la venta.
• Registrar la fecha de la venta en el canal "soldAt".
• Registrar la fecha de última actualización de la venta en Multivende "updatedAt" para que puedas identificar si la venta ha sido modificada desde la última vez que la obtuviste.
• Luego de registrar la venta por primera vez se envía el stock actualizado de los productos en ella.

Artículo 5 - ¿Cómo enviar Documentos Tributarios a Multivende? (Requerido)

Detallamos cómo realizar la carga de los documentos electrónicos a las ventas.

Equipo Integraciones API Multivende

Conoce el proceso para interactuar de forma correcta con la API de Multivende para integrar tu OMS.

Para realizar tu interacción de forma correcta con la plataforma y permitir que tu integración OMS pueda sacar el máximo provecho de las herramientas que brindamos, es necesario iniciar aprendiendo información básica sobre nuestra API, para eso te pedimos leer 8 artículos básicos sobre la integración:

Artículo 1 - Todo lo que debes saber sobre Integraciones API(Requerido)

Detallamos cuáles son los pasos para que tu aplicación pueda conectarse a la cuenta del merchant y poder empezar a consultar sus datos.

Artículo 2 - API Mutivende - Postman(Requerido)

Conocerás más sobre nuestra API y su documentación en Postman.

Artículo 3 - Requisitos técnicos generales (Requerido):

Encontrarás la información asociada a las consideraciones técnicas que debes tener en cuenta para la integración.

Artículo 4 - Registro de ventas desde Multivende: Instrucciones para integrarlas en tu sistema(Requerido)

Conocerás cómo obtener las ventas e iniciar el proceso de logística. Este es un flujo complementario a los webhooks para repasar las ventas en un rango de fechas y horas dadas, se recomienda:

• Registrar el _id de la venta.
• Registrar la fecha de la venta en el canal "soldAt".
• Registrar la fecha de última actualización de la venta en Multivende "updatedAt" para que puedas identificar si la venta ha sido modificada desde la última vez que la obtuviste.
• Luego de registrar la venta por primera vez se envía el stock actualizado de los productos en ella.

Artículo 5 -Estados de una Orden Según el Tipo de Entrega(Requerido)

Encontrarás la información para poder notificar al canal el estado de manejo de una orden.

Artículo 6 - ¿Cómo generar y consultar etiquetas de los Marketplace?(Recomendado):

Conocerás cómo obtener las etiquetas de las ventas que son despachadas por el marketplace.

Artículo 7 - ¿Cómo cargar stock vía API?(Opcional)

Encontrarás la información para realizar la sincronización de stock a Multivende. Para hacerlo, debes hacer uso de los endpoints de la sección “stock”, te recomendamos dejar un cron que sincronice los stocks por lo menos una vez al día. Además de una opción para que el usuario pueda ejecutar el proceso manualmente.

Artículo 8 - Actualización de Precios(Opcional)

Podrás obtener la información para realizar la sincronización de precios a Multivende. Para hacerlo, debes hacer uso de los endpoints de la sección “prices”.

Artículo 9 - ¿Cómo enviar Documentos Tributarios a Multivende? (Opcional)

Detallamos cómo realizar la carga de los documentos electrónicos a las ventas.

Equipo Integraciones API Multivende

Conoce el proceso para interactuar de forma correcta con la API de Multivende para integrar tu POS.

Para realizar tu interacción de forma correcta con la plataforma y permitir que tu integración POS pueda sacar el máximo provecho de las herramientas que brindamos, es necesario iniciar aprendiendo información básica sobre nuestra API, para eso te pedimos leer 8 artículos básicos sobre la integración:

Artículo 1 - Todo lo que debes saber sobre Integraciones API(Requerido)

Detallamos cuáles son los pasos para que tu aplicación pueda conectarse a la cuenta del merchant y poder empezar a consultar sus datos.

Artículo 2 - API Mutivende - Postman(Requerido)

Conocerás más sobre nuestra API y su documentación en Postman.

Artículo 3 - Requisitos técnicos generales (Requerido):

Encontrarás la información asociada a las consideraciones técnicas que debes tener en cuenta para la integración.

Artículo 4 - ¿Cómo cargar stock vía API?(Requerido)

Encontrarás la información para realizar la sincronización de stock a Multivende. Para hacerlo, debes hacer uso de los endpoints de la sección “stock”, te recomendamos dejar un cron que sincronice los stocks por lo menos una vez al día. Además de una opción para que el usuario pueda ejecutar el proceso manualmente.

Artículo 5 - Registro de ventas desde Multivende: Instrucciones para integrarlas en tu sistema(Requerido)

Conocerás cómo obtener las ventas e iniciar el proceso de logística. Este es un flujo complementario a los webhooks para repasar las ventas en un rango de fechas y horas dadas, se recomienda:

• Registrar el _id de la venta.
• Registrar la fecha de la venta en el canal "soldAt".
• Registrar la fecha de última actualización de la venta en Multivende "updatedAt" para que puedas identificar si la venta ha sido modificada desde la última vez que la obtuviste.
• Luego de registrar la venta por primera vez se envía el stock actualizado de los productos en ella.

Artículo 6 - ¿Cómo enviar Documentos Tributarios a Multivende? (Requerido)

Detallamos cómo realizar la carga de los documentos electrónicos a las ventas.

Artículo 7 - Actualización de Precios(Opcional)

Podrás obtener la información para realizar la sincronización de precios a Multivende. Para hacerlo, debes hacer uso de los endpoints de la sección “prices”.

Artículo 8 -Estados de una Orden Según el Tipo de Entrega(Opcional)

Encontrarás la información para poder notificar al canal el estado de manejo de una orden.

Artículo 9 - Generación de etiquetas de los marketplace(Opcional):)

Conocerás cómo obtener las etiquetas de las ventas que son despachadas por el marketplace.

Equipo Integraciones API Multivende

Conoce el proceso para interactuar de forma correcta con la API de Multivende para tu integración con PIM.

Para realizar tu interacción de forma correcta con la plataforma y permitir que tu integración OMS pueda sacar el máximo provecho de las herramientas que brindamos, es necesario iniciar aprendiendo información básica sobre nuestra API, para eso te pedimos leer 8 artículos básicos sobre la integración:

Artículo 1 - Todo lo que debes saber sobre Integraciones API(Requerido)

Detallamos cuáles son los pasos para que tu aplicación pueda conectarse a la cuenta del merchant y poder empezar a consultar sus datos.

Artículo 2 - API Mutivende - Postman(Requerido)

Conocerás más sobre nuestra API y su documentación en Postman.

Artículo 3 - Requisitos técnicos generales (Requerido):

Encontrarás la información asociada a las consideraciones técnicas que debes tener en cuenta para la integración.

Artículo 4 - ¿Cómo crear productos desde tu sistema a Multivende?(Requerido)

Con información básica (SKUs, Nombre, Variantes)(Recomendado): Te dejamos los endpoint disponibles:

• Get products with scroll: Enumera los productos asociados al Merchant.
• Get product by id: Muestra los detalles de un producto por la ID.

Artículo 5 - ¿Cómo cargar stock vía API?(Requerido)

Encontrarás la información para realizar la sincronización de stock a Multivende. Para hacerlo, debes hacer uso de los endpoints de la sección “stock”, te recomendamos dejar un cron que sincronice los stocks por lo menos una vez al día. Además de una opción para que el usuario pueda ejecutar el proceso manualmente.

Artículo 6 - Actualización de Precios(Requerido)

Podrás obtener la información para realizar la sincronización de precios a Multivende. Para hacerlo, debes hacer uso de los endpoints de la sección “prices”.

Equipo Integraciones API Multivende

Conoce el proceso para interactuar de forma correcta con la API de Multivende y aprovechar las herramientas disponibles para integrar tu DTE.

Para realizar tu interacción de forma correcta con la plataforma y permitir que tu integración OMS pueda sacar el máximo provecho de las herramientas que brindamos, es necesario iniciar aprendiendo información básica sobre nuestra API, para eso te pedimos leer 8 artículos básicos sobre la integración:

Artículo 1 - Todo lo que debes saber sobre Integraciones API(Requerido)

Detallamos cuáles son los pasos para que tu aplicación pueda conectarse a la cuenta del merchant y poder empezar a consultar sus datos.

Artículo 2 - API Mutivende - Postman(Requerido)

Conocerás más sobre nuestra API y su documentación en Postman.

Artículo 3 - Requisitos técnicos generales (Requerido):

Encontrarás la información asociada a las consideraciones técnicas que debes tener en cuenta para la integración.

Artículo 4 - Registro de ventas desde Multivende: Instrucciones para integrarlas en tu sistema(Requerido)

Conocerás cómo obtener las ventas e iniciar el proceso de logística. Este es un flujo complementario a los webhooks para repasar las ventas en un rango de fechas y horas dadas, se recomienda:

• Registrar el _id de la venta.
• Registrar la fecha de la venta en el canal "soldAt".
• Registrar la fecha de última actualización de la venta en Multivende "updatedAt" para que puedas identificar si la venta ha sido modificada desde la última vez que la obtuviste.
• Luego de registrar la venta por primera vez se envía el stock actualizado de los productos en ella.
  
  

Artículo 5 - ¿Cómo enviar Documentos Tributarios a Multivende? (Requerido)

Detallamos cómo realizar la carga de los documentos electrónicos a las ventas.

Equipo Integraciones API Multivende

Conoce el proceso para interactuar de forma correcta con la API de Multivende  para tu integración de sistema logístico.

Para realizar tu interacción de forma correcta con la plataforma y permitir que tu integración OMS pueda sacar el máximo provecho de las herramientas que brindamos, es necesario iniciar aprendiendo información básica sobre nuestra API, para eso te pedimos leer 8 artículos básicos sobre la integración:

Artículo 1 - Todo lo que debes saber sobre Integraciones API(Requerido)

Detallamos cuáles son los pasos para que tu aplicación pueda conectarse a la cuenta del merchant y poder empezar a consultar sus datos.

Artículo 2 - API Mutivende - Postman(Requerido)

Conocerás más sobre nuestra API y su documentación en Postman.

Artículo 3 - Requisitos técnicos generales (Requerido):

Encontrarás la información asociada a las consideraciones técnicas que debes tener en cuenta para la integración.

Artículo 4 - ¿Cómo cargar stock vía API?(Requerido)

Encontrarás la información para realizar la sincronización de stock a Multivende. Para hacerlo, debes hacer uso de los endpoints de la sección “stock”, te recomendamos dejar un cron que sincronice los stocks por lo menos una vez al día. Además de una opción para que el usuario pueda ejecutar el proceso manualmente.

Artículo 5 - Registro de ventas desde Multivende: Instrucciones para integrarlas en tu sistema(Requerido)

Conocerás cómo obtener las ventas e iniciar el proceso de logística. Este es un flujo complementario a los webhooks para repasar las ventas en un rango de fechas y horas dadas, se recomienda:

• Registrar el _id de la venta.
• Registrar la fecha de la venta en el canal "soldAt".
• Registrar la fecha de última actualización de la venta en Multivende "updatedAt" para que puedas identificar si la venta ha sido modificada desde la última vez que la obtuviste.
• Luego de registrar la venta por primera vez se envía el stock actualizado de los productos en ella.

Artículo 6 -Estados de una Orden Según el Tipo de Entrega(Requerido)

Encontrarás la información para poder notificar al canal el estado de manejo de una orden.

Artículo 7 - Generación de etiquetas de los marketplace(Requerido):

Conocerás cómo obtener las etiquetas de las ventas que son despachadas por el marketplace.

Equipo Integraciones API Multivende

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

En este artículo detallamos la información de la facturación referente a una venta según el Canal.

Lo primero que debes realizar es consultar la orden enviando el ID mediante el Endpoint Get Checkout, los detalles para la información de facturación puedes obtenerla dentro de nuestros campos normalizados en Multivende, consultando dentro de "Client" donde podrás obtener todos los datos relacionados al cliente y dentro del campo "BillingAddresses" los detalles en relación a la dirección de facturación.

"Client": {
  "fullName": "",
  "_id": "a8e48e5c-XXXX-4dab-9ec3-XXXXXXXXXXXX",
  "name": "",
  "lastName": "",
  "activity": null,
  "contactName": null,
  "comune": null,
  "city": null,
  "documentType": null,
  "taxId": "XXXXXXXX-X",
  "birthday": null,
  "code": null,
  "email": null,
  "phoneNumber": null,
  "comment": null,
  "type": "person",
  "tags": null,
  "status": "created",
  "createdAt": "2020-11-04T19:32:04.000Z",
  "updatedAt": "2020-11-04T19:32:04.000Z",
  "CreatedById": "af718539-XXXX-4413-8c83-XXXXXXXXXXXX",
  "UpdatedById": "68a88914-XXXX-414e-9d3c-XXXXXXXXXXXX",
  "ClientId": "a8e48e5c-XXXX-4dab-9ec3-XXXXXXXXXXXX",
  "MerchantId": "be133293-XXXX-4f01-822a-XXXXXXXXXXXX",
  "BillingAddresses": [
    {
      "_id": "30feddc9-XXXX-4951-816b-XXXXXXXXXXXX",
      "name": "Full Name",
      "address_1": "Coquimbo - IV - Coquimbo, Chile",
      "address_2": "General Bartolome Blanche XXX",
      "description": null,
      "indications": null,
      "position": 0,
      "status": "created",
      "importance": "principal",
      "createdAt": "2023-03-10T13:02:10.000Z",
      "updatedAt": "2023-03-10T13:02:10.000Z",
      "CreatedById": "af718539-XXXX-4413-8c83-XXXXXXXXXXXX",
      "UpdatedById": "68a88914-XXXX-414e-9d3c-XXXXXXXXXXXX",
      "ClientId": "a8e48e5c-XXXX-4dab-9ec3-XXXXXXXXXXXX",
      "MerchantId": "be133293-XXXX-4f01-822a-XXXXXXXXXXXX"
    }
  ]
}

• Para identificar la información de facturación del cliente debes consultar el campo "CheckoutBillingClients"

"CheckoutBillingClients": [
  {
    "_id": "9f1839df-XXXX-4a05-XXXX-2e4024XXXXXX",
    "name": "Multivende",
    "taxName": null,
    "taxActivity": null,
    "taxId": "XXXXXXXXX",
    "documentType": "RUT",
    "legalRepresentative": null,
    "legalRepresentativeTaxId": null,
    "email": null,
    "phoneNumber": null,
    "type": "company" or "person"
    "status": "created",
    "createdAt": "2024-01-12T12:41:08.000Z",
    "updatedAt": "2024-01-12T12:41:08.000Z",
    "BillingAddressId": "02e22a7b-7850-4204-8728-78a888ae09c7",
    "CheckoutId": "0d85a156-9c81-XXXX-XXXX-7908e8XXXXXX",
    "CreatedById": null,
    "UpdatedById": null,
    "MerchantId": "4df759c7-XXXX-4cad-XXXX-a5e954XXXXXX"
  }
]

Dafiti  y Falabella

Esta se informa dentro del campo "InvoiceRequired"

• Boleta:

{
  "InvoiceRequired: "false",
}

• Factura:

{ 
  "InvoiceRequired: "true", 
}

Mercadolibre

Se informa dentro de:

"remote_order_extra_billing_information" → "buyer" → "attributes" → "cust_type"

• Si la orden de compra es una Persona Física (Cliente) llegará de la siguiente manera:

{ "remote_order_billing_information": 
 { "buyer": 
  { "billing_info": 
   { "attributes": 
    { "cust_type": "CO" 
    } 
   } 
  } 
 } 
} 

• Si la orden de compra es una Persona Jurídica (Empresa) llegará de la siguiente manera:

{ "remote_order_billing_information": 
 { "buyer": 
  { "billing_info": 
   { "attributes": 
    { "cust_type": "BU" 
    } 
   } 
  } 
 } 
} 

Paris

Se informa dentro del campo "originInvoiceType".

• Boleta:

{
  "originInvoiceType: "boleta,
}

• Factura:

{
  "originInvoiceType: "factura,
}

Ripley

Se informa dentro del campo "has_invoice"

• Boleta:

{
  "has_invoice: "false,
}

• Factura:

{
  "has_invoice: "true",
}

Shopify

Se informa dentro de los campos "CheckoutLink" --> "tags"

"tags": [
  "FACTURA",
]

VTEX

Se informa dentro del campo "clientProfileData" --> "isCorporate"

{
  "isCorporate: true // Factura
}

Equipo Integraciones API Multivende

Se pueden adjuntar archivos tanto las ventas (Checkouts) como los despachos (DeliveryOrder) en formato PDF con un peso máximo de 1MB, para ello se requiere identificar los respectivos _ids de la venta o del despacho.

Primero se tiene que crear un registro en Multivende del DTE usando el siguiente endpoint Create checkout electronic billing document, dentro del body estarás enviando la siguiente información: 

• Checkout_id (Identificador único de la venta en Multivende).
• ClientId (se obtiene desde el Client en el detalle de la venta consultando el Endpoint Get Checkout).
• id (Número de folio correspondiente al documento a ser cargado).
• Fecha de emisión.
• type (se detalla más adelante).
• provider (se detalla más adelante).
• ElectronicBillingDocumentEmitterId (se detalla más adelante).

Request:

curl --location -g '{{base_url}}/api/checkouts/{{checkout_id}}/electronic-billing-documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "ClientId": "{{client_id}}",
  "id": "XXXXXXX",
  "emissionDate": "2019-03-01",
  "type": "electronic_billing_electronic_bill",
  "provider": "test_provider_code",
  "ElectronicBillingDocumentEmitterId": "{{electronic_billing_document_emitter_id}}"
}'

Response:

{
  "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "status": "created",
  "ClientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "id": "8877777",
  "emissionDate": "2019-03-01T00:00:00.000Z",
  "ElectronicBillingDocumentEmitterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "CreatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "UpdatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "ElectronicBillingDocumentTypeId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "ElectronicBillingDocumentProviderId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "CheckoutId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "updatedAt": "2019-08-29T15:26:33.000Z",
  "createdAt": "2019-08-29T15:26:33.000Z"
}

Una vez se cree el registro del DTE, con el "_Id" del response, se adjuntan los archivos, tenemos dos endpoints que permiten realizar la carga de archivos en  pdf o base64:

• El endpoint Upload file to electronic billing document  permite la carga del archivo PDF desde local.
• El endpoint Upload file to electronic billing document base64  permite la carga del archivo Base64.

La carga de los DTE desde Multivende a los canales de venta se tiene habilitado para:

• Mercado Libre
• Paris
• Ripley
• Falabella
• Coppel
• Walmart (Habilitado sólo para México)
• VTEX

A continuación te detallamos algunas consideraciones a tener en cuenta en la carga de los documentos tributarios para los siguientes canales de ventas: 

Consideraciones para VTEX

Consideraciones para Falabella

De lo contrario el documento quedará con error de sincronización.

Consideraciones para Walmart México

Subir documentos electrónicos a los despachos

Primero se tiene que crear el registro en Multivende del DTE usando el siguiente endpoint Create delivery order electronic billing document 

Para lo que se requiere conocer:

• Delivery_order_id (Id del despacho).
• ClientId (se obtiene del detalle de la venta).
• id (número de folio).
• Fecha de emisión.
• type (se detalla más adelante).
• provider (se detalla más adelante).
• ElectronicBillingDocumentEmitterId (se detalla más adelante).

Response: 

Una vez se cree el registro del DTE, con el _id del response, se adjunta como tal los archivos (.pdf, .zip, entre otros) por medio del endpoint Upload file to electronic billing document.

Códigos de tipos (type) permitidos para los DTEs

• electronic_billing_electronic_invoice (Factura Electrónica)
• electronic_billing_not_taxed_electronic_invoice (Factura Electrónica Exenta)
• electronic_billing_electronic_bill (Boleta Electrónica)
• electronic_billing_not_taxed_electronic_bill (Boleta Electrónica Exenta)
• electronic_billing_not_taxed_debit_note
• electronic_billing_not_taxed_credit_node

Para los Providers (proveedor)

Esta información se tiene que canalizar vía correo api@multivende.com solicitando un código de proveedor según el proveedor (generador de boletas) que estén usando. Enviando la siguiente información:

• Sistema DTE.
• Empresa desarrolladora de la integración.
• Merchant ID.

Multivende genera el código y lo informa de vuelta en el correo de la solitud.

Para los Emisores de documentos (ElectronicBillingDocumentEmitterId)

Puedes seguir los pasos del siguiente artículo ¿Cómo crear un emisor de documentos?.  En caso de cualquier duda comunicarse con onboarding@multivende.com , ellos lo asistirán en la generación de este identificador.

Si deseas realizar este proceso via API, puedes crear el emisor de documentos mediante el endpoint Create electronic billing document emitter enviando los siguientes campos:

*Rellena el campo código con 01111

En la respuesta del endpoint puedes identificar el _id asociado al emisor del documento electrónico, este proceso se realiza sólo una vez y el emisor de documento electrónico queda asociado a la cuenta del merchant.

Response: 

Puedes consultar el _id del emisor de documento asociado a la cuenta de un merchant mediante el endpoint: Get electronic billing document emitters

Consulta de documentos electrónicos

Para consultar los documentos electrónicos de una orden puedes consultar al siguiente endpoint Get electronic billing documents of a checkout

Consideraciones para tipos de envío Fulfillment

Si se trata de una orden de tipo Fulfillment, recuerda que para verificar el tipo de envío debes consultar el campo "shippingMode".

Paris: 

• El seller debe solicitar la configuración de Fulfillment a Paris, y el canal se encarga de emitir la boleta.

Mercadolibre:

• Argentina, Colombia y México, el vendedor puede generar la factura.
• Brasil y Chile, Mercado Libre siempre genera la factura.

Falabella

• Falabella se encarga de la emisión de la boleta.

Ripley

• Para registrar tus ventas de Fulfillment by Ripley desde Multivende, es necesario que tengas una cuenta nueva creada en Ripley. Asegúrate de tener este requisito cumplido antes de solicitar la integración. La boleta es generada por el marketplace para estas ventas.

Equipo Integraciones API Multivende

En este artículo mostramos como obtener la información del pago realizado por el comprador en la venta.

Esta información la obtenemos mediante los siguientes Endpoints que tenemos disponibles dentro de nuestro Servicios de Integración de Multivende.

Obtener la información del pago de una venta

• Get checkout: Adicional a obtener los detalles de una venta, tales como datos del cliente y facturación puedes encontrar los detalles del pago consultando el campo "CheckoutPayments" aquí podrás visualizar los métodos de pago utilizados en la venta.

Ejemplo Response: 

Métodos de Pago

• Get checkout payment methods: Se detallan los métodos de pago asociados a la cuenta del Merchant, enviando dentro del Request el MerchantId se listará el ID del método de pago, nombre, descripción, entre otros. Los cuales son estándar para todos los merchants de Multivende y puedes dejarlos preconfigurados al realizar la integración para homologarlos con los de la aplicación.

Ejemplo Response: 

Actualizar información del pago de una venta

• Update checkout payment: Te permite actualizar los detalles de un pago, no es obligatorio enviar todos los campos del cuerpo. Solo se deben enviar aquellos que necesitan ser actualizados.

Los valores permitidos para enviar dentro del campo “verificationStatus” es "verified" o "pending"

Nota: esta funcionalidad sólo es permitida para las integraciones que son de tipo Canal de venta, las cuales pueden notificar los estados de los pagos hacia Multivende. 

Ejemplo Request:

Ejemplo Response:

Equipo Integraciones API Multivende

Cuando un comprador adquiere un Kit (Pack) en MercadoLibre, se genera una única venta que represente al kit completo.

En su lugar:

• MercadoLibre crea una orden de venta por cada ítem que compone el kit.
• Todas esas órdenes:
  • Corresponden a una misma venta en Multivende
  • Están relacionadas entre sí
  • Comparten información común como el envío y el pack

Implicaciones importantes:

• Siempre habrá múltiples órdenes para una venta de kit en Mercadolibre lo que en Multivende se traduce como un mismo checkout, debido a que Mercadolibre los asocia como un mismo pack. 
• Cada orden representa un producto específico del kit y el descuento del stock va asociado a cada ítem componente del kit. Esto quiere decir que las órdenes de kit van a mostrar los productos componentes del pack y no el pack en si.
   

Flujo general para identificar una venta de Kit vía API Multivende:

El proceso recomendado para un integrador de Multivende es el siguiente:

1. Leer la venta usando el endpoint de Get Checkout
2. Validar si la orden corresponde a un Kit mediante el campo tags, dentro de esta respuesta, se debe revisar el campo "tags": "pack_order,kit_component,kit,paid,not_delivered,test_order".

Tags clave a validar:

• Kit
• Kit_component

Interpretación: Si alguno de estos tags está presente, la venta contiene productos de kit.

3. Si deseas identificar todas los números de las órdenes de Mercadolibre relacionadas al Kit lo puedes hacer usando externalContent -> kit_orders, esto es un paso no requerido.

Este campo contiene un arreglo con la información de cada orden que compone el kit.

Ejemplo de kit_orders:

"kit_orders": [
  {
    "order_id": 200001408888XXXX,
    "item_id": "MLB595574XXXX",
    "variation_id": null,
    "pack_id": 20000103169XXXX,
    "shipment_id": 4598979XXXX,
    "parent_item_id": "MLB595731XXXX"
  },
  {
    "order_id": 20000140888XXXX,
    "item_id": "MLB595581XXXX",
    "variation_id": null,
    "pack_id": 200001031698XXXX,
    "shipment_id": 4598979XXXX,
    "parent_item_id": "MLB595731XXXX"
  },
  {
    "order_id": 200001408888XXXX,
    "item_id": "MLB595585XXXX",
    "variation_id": null,
    "pack_id": 200001031698XXXX,
    "shipment_id": 4598979XXXX,
    "parent_item_id": "MLB595731XXXX"
  }
]

Cada objeto dentro de kit_orders representa una orden individual del kit:

• Todos las órdenes comparten el mismo: 
  • Pack_id
  • shipment_id , ya que se envían juntos
  • parent_item_id,  identifica el producto principal del Kit
     

Cualquier duda o consulta adicional referente a este artículo, puedes escribirnos a api@multivende.com.

Encuentra aquí el proceso necesario para sincronizar información de productos hacia canales de venta.

El objetivo es facilitar que los merchants puedan gestionar y relacionar toda la información de sus productos de manera eficiente.

• Proceso de Sincronización y Publicación

Para lograr la publicación exitosa de un producto en un canal de venta, se requiere seguir los siguientes pasos de configuración de información, los cuales deben ser implementados del lado del canal de venta.

Mapeo general: Configuración de los datos de las credenciales para establecer la conexión entre Multivende y el canal de venta. Permite al comerciante vincular ambos sistemas.

Mapeo de categorías : Establecer la relación entre las categorías de productos en Multivende y las categorías correspondientes en el canal de venta. Las categorías de la cuenta del merchant en Multivende pueden ser obtenidas mediante el endpoint: Get product categories.

Mapeo de atributos: Relacionar los atributos personalizados creados en Multivende con los atributos equivalentes disponibles en el canal de venta. Los atributos deben estar asociados por categorías. El único atributo que debe quedar configurado por defecto es el SKU (code).
Para obtener un array con todos los atributos de los productos de Multivende para un Merchant usar el endpoint Get product attributes.

Mapeo de marcas:Relacionar cada una de las marcas creadas en Multivende con la marca correspondiente en el canal de venta.

Para consultar las marcas de una cuenta de merchant dentro de Multivende puedes hacerlo mediante el endpoint: Get brands.

Imágenes: las imágenes están clasificadas por álbum. Para obtener el listado de los álbumes usar el endpoint Get products picture set. (El Merchant debe poder seleccionar qué álbum de fotos que va a usar). En caso de usar el álbum por defecto de Multivende debes considerar que el _id de este álbum es el valor "null". 

Publicación de los productos en el canal:

Para consultar todo el detalle de la información de un producto lo haces por el id de Multivende del producto mediante el endpoint Get product by id.

La publicación de los productos en el canal de venta se puede realizar mediante dos modalidades:

• Publicar desde el canal

Esta vista debe listar los productos de la cuenta del merchant en Multivende y permitir la publicación masiva o individual de los  productos. La vista debe ser realizada de lado de la integración.

Para leer los productos desde Multivende hacia el canal de venta debes realizar la consulta mediante el polling de productos con el endpoint de Get products with scroll.

• Publicación mediante product links:

En Multivende, el merchant, puede activar los productos de forma individual o masiva, generando un `product link`. Este enlace contiene información del estado del producto entre el  canal de ventas y Multivende.

Los product links serán notificados vía webhook y también pueden ser consultados mediante la        api con el endpoint de Get product links with scroll para respaldar cualquier notificación que no          haya sido recibida.

Al consultar el detalle del product link mediante el endpoint de Get product link by id en la respuesta de la api,  se puede validar el estado de sincronización para el producto enviado.

Los estados de sincronización asociados a un product link son:

• “not-synchronized” : el producto fue enviado para ser sincronizado, este estado es recepcionado por el canal para iniciar la publicación del producto.
• “synchronized”: el producto fue publicado exitosamente en el canal de venta, este estado es notificado por el canal de venta hacia Multivende mediante una actualización del estado de sincronización.
• “synchronized_with_warnings”: el producto se sincronizó, sin embargo se requiere de cierta información, que si bien no afecta la publicación del producto, debe ser corregida o enviada para que la publicación quede cien por ciento sincronizada.
• “synchronizing”:  el producto se encuentra en sincronización con el canal de venta, este estado es usado por los canales que requieren una revisión del producto antes de ser publicado.
• “failed”: la sincronización del producto con el canal falló y no se logró la publicación. El canal debe enviar la descripción o detalle del error para que el merchant pueda realizar las correcciones pertinentes.

Realizar actualizaciones de estados de sincronización hacia Multivende.

Las actualizaciones de estados de los product links notifican hacia Multivende el resultado de la            vinculación del producto con el canal de venta. Esta comunicación de product links es bi-                      direccional entre Multivende y el canal de venta.

Las integraciones de canal de venta reciben la notificación via webhook o la lectura via polling de          las actualizaciones de los product links que se realicen desde Multivende y a partir de allí deben            informar hacia Multivende el estado en que se encuentra el producto en el canal.

El endpoint para enviar los de estados de sincronización hacia Multivende es: Post Upsert product link, se deben pasar los siguientes parámetros:

• 'ProductId': id de el producto padre en Multivende

• 'externalId': corresponde al identificador del producto en el canal

• 'externalContent': se informa la data nativa del canal (JSON)

• 'extraData': cualquier otra información relevante

• 'synchronizationStatus': permite los siguientes estados

           -> 'not-synchronized'

           -> 'synchronized'

           -> 'synchronized_with_warnings'

           -> 'synchronizing'

           -> 'Failed'

Los estados de sincronización de los productos entre Multivende y el canal de venta, los merchants los pueden ver en el panel de control del front de Multivende:

Y también en la conexión con la aplicación:

Despublicar el producto en el canal de venta

Si un usuario requiere remover productos en el canal, puede hacerlo desde Multivende, apagando el producto en la conexión, esta acción registra el estado de sincronización del producto como “to_unpublish”.

El canal de venta debe notificar a Multivende que la publicación del producto en el canal fue eliminada mediante el endpoint:  Deleted product link , el estado de sincronización del producto se actualiza a “to_unpublish” y es removido de la conexión, si el producto es nuevamente activado, el estado de sincronización llegará como “to_republish” y puede ser sincronizado nuevamente.

Si se desea remover el producto directamente desde el canal, sólo se debe enviar la solicitud del  Deleted product link. Este endpoint permite eliminar uno o varios productos directamente de la conexión.

Mapeo de precios

El merchant debe poder seleccionar la lista de precios mediante la cual el canal tomará la información de los valores de precios de los productos. Para consultar las listas de precios asociadas a un merchant usamos el endpoint Get price lists 

Posteriormente puedes consultar el precio de los productos mediante el endpoint Get prices with scroll, enviando el id de la lista de precios, límite de items a consultar (el rango del límite permitido es >=50 y <=30000), este endpoint permite obtener el precio de los productos paginados por scroll.

Puedes consultar el precio por un rango de fecha y hora, filtrando por el parámetro de fecha de creación (createdAt) o fecha de actualización (updatedAt).

Mapeo de inventario

En esta vista el merchant selecciona la bodega desde la cual se tomará el stock de los productos publicados en el canal. Para consultar las bodegas de la cuenta de un usuario en Multivende hacemos un llamado al endpoint Get stocks and warehouses.

Puedes consultar el stock de los productos mediante el endpoint Get stocks with scroll, enviando el id de la bodega, límite de items a consultar (el rango del límite permitido es >=50 y <=30000), este endpoint permite obtener el stock de los productos paginados por scroll.

 Puedes consultar el stock por un rango de fecha y hora, filtrando por el parámetro de fecha de creación (createdAt) o fecha de actualización (updatedAt).

Esperamos que este artículo te haya proporcionado una guía detallada para asegurar que la información de los productos se sincronice correctamente entre Multivende y los canales de venta, incluyendo los pasos necesarios y los endpoints de la API para realizar estas acciones.

Equipo Integraciones API Multivende

En este artículo, mostramos cómo realizar la creación de productos desde tu sistema hacia Multivende.

Para comenzar, te dejamos los Endpoints disponibles para una correcta creación de un producto desde nuestra API.

• Get products with scroll: Obtener todos los productos de un Merchant.
• Products: Obtener los registros de las marcas, tallas, colores u otros se debe consultar según sea el caso en la carpeta correspondiente.
• Create product: Crear productos asociado a un merchant.
• Update product: Permite actualizar la información del producto.
• Atributos custom: Atributos personalizados que pueden asignar al producto.

Te recomendamos leer el siguiente artículo en donde abordamos esto con mayor detalle.

Creación de un producto con información básica

A través de nuestra API podemos realizar la creación de un producto para ello disponemos del Endpoint Create product *, esto nos permite crear un producto a un Merchant.

Te dejamos un ejemplo para la creación de un producto enviando información básica dentro del cuerpo del mensaje, cabe destacar que debes ponerle un Nombre y configurar el SKU padre e hijo.

{
  "name": "Nombre del producto",
  "code": "SKU Padre",
  "InventoryTypeId": "791a6654-c5f2-11e6-aad6-2c56dc130c0d",
  "InternalCodeTypeId": null,
  "ProductVersions": [
    {
      "status": "waiting-for-creation",
      "code": "SKU Hijo",
      "isDefaultVersion": true,
      "InventoryTypeId": "791a6654-c5f2-11e6-aad6-2c56dc130c0d",
      "InternalCodeTypeId": null,
      "position": 0
    }
  ]
}

Tener en consideración utilizar siempre el campo “InventoryTypeId” seteado de la siguiente manera  = "791a6654-c5f2-11e6-aad6-2c56dc130c0d".

Una vez enviado el endpoint la API no retornará 201, indicando la creación de nuestro producto de forma exitosa, un ejemplo del response es el siguiente:

{
  "_id": "XXX33b34-XXXX-XXXX-85e2-5b55a0aXXXXXX",
  "status": "created",
  "name": "Nombre del producto",
  "InternalCodeTypeId": null,
  "code": "SKU Padre",
  "CreatedById": "d561f14f-0800-4091-8d3f-XXXXXXXXXXXX",
  "UpdatedById": "d561f14f-0800-4091-8d3f-XXXXXXXXXXX",
  "MerchantId": "bf03e4e6-53a0-4082-9476-XXXXXXXXXXX",
  "updatedAt": "2023-00-00T00:00:00.000Z",
  "createdAt": "2023-00-00T00:00:00.000Z",
  "ProductTypeId": "0f381d1c-3408-11e7-8e63-XXXXXXXXXXXX",
  "ProductVersions": [
    {
      "_id": "d775b3d8-a19a-4069-8cdd-XXXXXXXXXXXX",
      "code": "SKU Hijo",
      "internalCode": null,
      "providerCode": null,
      "position": 0,
      "width": 0,
      "length": 0,
      "height": 0,
      "weight": 0,
      "status": "created",
      "createdAt": "2023-00-00T00:00:00.000Z",
      "updatedAt": "2023-00-00T00:00:00.000Z",
      "CodeTypeId": null,
      "InternalCodeTypeId": null,
      "ColorId": "4ecf5004-f721-46bf-a38a-75807491a4cb",
      "SizeId": "226a61dc-1eef-41cf-af5e-cc6aea7c75b4",
      "CreatedById": "d561f14f-0800-4091-8d3f-XXXXXXXXXXXX",
      "UpdatedById": "d561f14f-0800-4091-8d3f-XXXXXXXXXXXX",
      "InventoryTypeId": "791a6654-c5f2-11e6-aad6-XXXXXXXXXXXX",
      "ProductId": "30433b34-294f-40a6-85e2-XXXXXXXXXXXX",
      "MerchantId": "bf03e4e6-53a0-4082-9476-XXXXXXXXXXXX"
    }
  ]
}

Tener en consideración la lectura de los siguientes artículos, dado que una vez creado este producto puedes realizar la carga del Stock y el Precio.

• ¿Cómo cargar stock vía API?: Mostramos cómo realizar las carga de stock de tus productos mediante la API de Multivende.
• Actualización de Precios: Te indicamos cómo realizar una actualización de precio para tus productos.

Crear un producto con información completa.

Del mismo modo utilizando el Endpoint Create product * podemos crear un producto pero enviando información completa de este, ya sea color, talla, marca, etc.

Antes de comenzar a crear un producto al detalle lo primero que debes realizar es lo siguiente:

1.- Mapeo de los atributos de los productos como:

1. Categoría.
2. Color.
3. Talla.
4. Marca.
5. Temporada.
6. Clases de envío.
7. Descripción.
8. Atributos custom. 
9. El único atributo que debe quedar configurado por defecto es el SKU (code).

Para obtener un array con todos los atributos de los productos de Multivende para un Merchant usar en endpoint Get product attributes.

2.- Imágenes: 

Las imágenes están clasificadas por álbum para obtener el listado de los álbumes usar el endpoint Get products picture set. (El Merchant deberá poder mapear los álbumes de la aplicación con los álbumes de Multivende).

• Configuración imágenes de producto: Contiene los Endpoint para realizar actualizaciones de posiciones de imágenes, subir imágenes por ID o URL, cargar imágenes hacia la versión del producto.
• Get products picture set: Obtendrás los álbumes de imágenes de los productos del Merchant.
• Get products pictures: Lista las imágenes de un producto del Merchant.

Si el campo "ProductPictureSetId" es "null", es el álbum predeterminado.

• Get product versions pictures: Obtiene las imágenes de las versiones de un producto del Merchant

Puedes encontrar más detalles en el artículo dedicado a la Gestión de imágenes.

*El Merchant deberá poder seleccionar cuales son los productos que cargará desde la aplicación a Multivende.

Configuración de atributos

Puedes encontrar el detalle de los Endpoint en la propia documentación de la API, no obstante te dejamos los que podrían ser los más relevantes:

• Marcas:

Get Brands: Podrás obtener las marcas asociadas al Merchant.

Get Brands by Id: Te permite buscar una marca especifica enviando el "_id" dentro del request.

Post Brands: Puedes crear una marca desde la integración la cual quedará asociada al Merchant.

Update Brands: Te permite actualizar el nombre o la descripción de la marca.

• Clases de envío:

Get shipping classes: Podrás obtener las clases de envío asociadas al Merchant.

Get shipping classes by Id: Te permite buscar una clase envío especifica enviando el "_id" dentro del request.

Post shipping classes: Puedes crear una clase de envío desde la integración la cual quedará asociada al Merchant.

• Colores:

Get Colors:  Podrás obtener los colores asociados al Merchant.  

Get Colors by Id: Te permite buscar un color especifico enviando el "_id" dentro del request.

Post Colors: Puedes crear un color el cual quedará asociado al Merchant.

Update Colors: Te permite actualizar el nombre del color.

• Tallas:

Get Sizes: Podrás buscar las tallas asociadas al Merchant. 

Get Size by Id: Te permite buscar una talla especifica enviando el "_id" dentro del request.

Post Sizes: Puedes crear un talla la cual quedará asociada al Merchant.

Update Sizes: Te permite actualizar el nombre y la descripción de la talla.

• Temporadas:

Get Seasons: Podrás obtener las temporadas asociadas al Merchant.  

Get Seasons by Id: Te permite buscar una temporada especifica enviando el "_id" dentro del request.

Post Seasons: Puedes crear una temporada la cual quedará asociada al Merchant.

Update Seasons: Te permite actualizar el nombre de la temporada.

• Categorías:

Get Product Categories: Podrás obtener las categorías de los productos asociadas al Merchant.

Get Product Categories by Id: Te permite buscar una categoría de un producto enviando el "_id" dentro del request.

Post Product Categories: Puedes crear una categoría la cual quedará asociada al Merchant.

Update Categories: Te permite actualizar el nombre y la descripción de la categoría.

Equipo Integraciones API Multivende

En este artículo, mostramos como actualizar un producto desde tu sistema hacia Multivende mediante nuestra API.

Para comenzar, te dejamos los endpoints disponibles para una correcta actualización de un producto desde nuestra API.

• Get products with scroll: Obtener todos los productos de un Merchant.
• Products: Obtener los registros de las marcas, tallas, colores u otros se debe consultar según sea el caso en la carpeta correspondiente.
• Create product: Crear productos asociado a un merchant.
• Atributos custom: Atributos personalizados que pueden asignar al producto.

A través de nuestra API podemos realizar la actualización de un producto para ello disponemos del Endpoint Update Product.

Dentro del "Body" podrás enviar los parámetros que deseas modificar, como por ejemplo "name", "alias" o un "CustomAttributeValues".

Te dejamos un ejemplo para la actualización de un producto enviando información básica dentro del cuerpo del mensaje.

{
  "name": "TEST Guantes Nike Extreme Lightweight Fitness Para Hombre",
  "alias": "",
  "BrandId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "model": "",
  "SeasonId": null,
  "description": null,
  "ProductVersions": [
    {
      "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "code": "NLGC4937_L",
      "SizeId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "ColorId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "status": "created",
      "internalCode": "",
      "CodeTypeId": null,
      "InternalCodeTypeId": null,
      "position": 0,
      "width": 0,
      "length": 0,
      "height": 0,
      "weight": 0,
      "Size": {
        "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "L"
      },
      "CodeType": {
        "_id": null,
        "name": null,
        "code": null,
        "description": null,
        "position": null,
        "tags": null,
        "status": null,
        "createdAt": null,
        "updatedAt": null
      },
      "InternalCodeType": {
        "_id": null,
        "name": null,
        "code": null,
        "description": null,
        "position": null,
        "tags": null,
        "status": null,
        "createdAt": null,
        "updatedAt": null
      },
      "Color": {
        "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "Negro"
      },
      "InventoryType": {
        "_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "INVENTORY_TYPES.Normal.Name",
        "code": "_normal_inventory_type",
        "description": "INVENTORY_TYPES.Normal.Description",
        "position": 0,
        "tags": "NULL",
        "status": "created",
        "createdAt": null,
        "updatedAt": null
      },
      "ProductVersionPictures": [null],
      "CustomAttributeValues": {
        "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": "L"
      },
      "allImages": [],
      "InventoryTypeId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
  ],
  "ProductCategoryId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "code": "NLGC4937",
  "internalCode": "",
  "CodeTypeId": null,
  "shortDescription": "",
  "htmlDescription": "",
  "htmlShortDescription": "",
  "tags": [],
  "WarrantyId": null,
  "ShippingClassId": null,
  "CustomAttributeValues": {
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": "negro",
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": "xNLGC4937",
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  },
  "OfficialStoreId": null,
  "InventoryTypeId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "InternalCodeTypeId": null
}

Importante:

• Recordar que siempre el campo “InventoryTypeId” debe ir establecido de la siguiente manera:

  "InventoryTypeId": "791a6654-c5f2-11e6-aad6-2c56dc130c0d"

• Dentro del body puede enviar únicamente los parámetros que deseas actualizar, el resto, puedes omitirlos o no enviarlos en la solicitud.

Equipo Integraciones API Multivende

En este artículo te mostramos cómo consultar el stock de tus productos mediante la API de Multivende.

La consulta de stock se realiza a productos asociados a una bodega en Multivende. Para consultar las bodegas que se encuentran creadas en una cuenta de merchant, lo puedes hacer mediante el endpoint: Get stores and warehouses.

Request:

curl --location -g '{{base_url}}/api/m/{{merchant_id}}/stores-and-warehouses/p/{{page}}' \

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

Response:

{
  "entries": [
    {
      "_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Mi Tienda (Personaliza el nombre)",
      "code": null,
      "address": null,
      "description": null,
      "type": "store",
      "phoneAreaCode": null,
      "phoneNumber": null,
      "latitude": 0,
      "longitude": 0,
      "openHours": null,
      "tags": null,
      "position": 0,
      "status": "created",
      "createdAt": "2018-05-24T00:19:31.000Z",
      "updatedAt": "2018-05-24T00:19:31.000Z",
      "CreatedById": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "UpdatedById": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "LocationId": null,
      "TimezoneId": null,
      "MerchantId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "SalesGroupId": null
    },
    {
      "_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Bodega (Personaliza el nombre)",
      "code": null,
      "address": null,
      "description": null,
      "type": "warehouse",
      "phoneAreaCode": null,
      "phoneNumber": null,
      "latitude": 0,
      "longitude": 0,
      "openHours": null,
      "tags": null,
      "position": 1,
      "status": "created",
      "createdAt": "2018-05-24T00:19:31.000Z",
      "updatedAt": "2018-05-24T00:19:31.000Z",
      "CreatedById": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "UpdatedById": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "LocationId": null,
      "TimezoneId": null,
      "MerchantId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "SalesGroupId": null
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "total_pages": 1,
    "current_page": 1,
    "next_page": 0,
    "previous_page": 0,
    "total_items": 2
  }
}

Consultar stock de productos

Puedes consultar el stock de los productos mediante el endpoint Get stocks with scroll, enviando:

• el id de la bodega
• límite de items a consultar (el rango del límite permitido es >=50 y <=5000)

Este endpoint permite obtener el stock de los productos en una bodega paginados por scroll.

Puedes consultar el stock por un rango de fecha y hora, filtrando por el parámetro de fecha de creación (createdAt) o fecha de actualización (updatedAt). Esta modalidad es requerida para aquellas integraciones que realicen consultas frecuentes de stocks, se recomienda que la ventana de búsqueda no sea mayor a 2 horas respecto a la última búsqueda realizada.

Consultar el histórico de movimientos de stock de un producto en una bodega

El historial de stock en bodega, puede ser consultado a través del endpoint Get stock history
este retorna todo el movimiento de stock del producto.

Podrás visualizar la información que se ve en la vista Movimiento de inventario desde la plataforma de Multivende.

Ejemplo response:

{
  "entries": [
    {
      "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "date": "2019-03-07T18:14:15.000Z",
      "amount": 76,
      "unitCost": 0,
      "type": "INCREASE",
      "comment": null,
      "status": "created",
      "createdAt": "2019-03-07T18:14:15.000Z",
      "updatedAt": "2019-03-07T18:14:15.000Z",
      "CreatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "UpdatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "CostCurrencyId": null,
      "OriginProviderId": null,
      "ProductRelocationCategoryId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "OriginWarehouseId": null,
      "DestinationWarehouseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "ProductVersionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "ProductStockBatchId": null,
      "ProductRelocationCategory": {
        "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "name": "PRODUCT_RELOCATION_CATEGORIES.Product_reception.Name",
        "certaintyLevel": "known",
        "type": "increase",
        "code": "_product_reception",
        "description": "PRODUCT_RELOCATION_CATEGORIES.Product_reception.Description",
        "position": 0,
        "tags": "{ \"use_type\": \"external\"}",
        "status": "created",
        "createdAt": null,
        "updatedAt": null
      },
      "CreatedBy": {
        "profile": {
          "name": "developers",
          "fullName": "developers"
        },
        "token": {
          "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
        },
        "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "name": "developers",
        "email": "developers-test@multivende.com"
      },
      "OriginWarehouse": null,
      "DestinationWarehouse": {
        "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "name": "Bodega (Personaliza el nombre)",
        "code": null,
        "address": null,
        "description": null,
        "type": "warehouse",
        "phoneAreaCode": null,
        "phoneNumber": null,
        "latitude": 0,
        "longitude": 0,
        "openHours": null,
        "tags": null,
        "position": 1,
        "status": "created",
        "createdAt": "2019-01-30T17:18:46.000Z",
        "updatedAt": "2019-01-30T17:18:46.000Z",
        "CreatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "UpdatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "LocationId": null,
        "TimezoneId": null,
        "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "SalesGroupId": null
      }
    },
    {
      "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "date": "2019-03-07T18:04:49.000Z",
      "amount": 14,
      "unitCost": 0,
      "type": "INCREASE",
      "comment": null,
      "status": "created",
      "createdAt": "2019-03-07T18:04:49.000Z",
      "updatedAt": "2019-03-07T18:04:49.000Z",
      "CreatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "UpdatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "CostCurrencyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "OriginProviderId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "ProductRelocationCategoryId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "OriginWarehouseId": null,
      "DestinationWarehouseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "ProductVersionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
      "ProductStockBatchId": null,
      "ProductRelocationCategory": {
        "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "name": "PRODUCT_RELOCATION_CATEGORIES.Product_reception.Name",
        "certaintyLevel": "known",
        "type": "increase",
        "code": "_product_reception",
        "description": "PRODUCT_RELOCATION_CATEGORIES.Product_reception.Description",
        "position": 0,
        "tags": "{ \"use_type\": \"external\"}",
        "status": "created",
        "createdAt": null,
        "updatedAt": null
      },
      "CreatedBy": {
        "profile": {
          "name": "developers",
          "fullName": "developers"
        },
        "token": {
          "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
        },
        "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "name": "developers",
        "email": "developers-test@multivende.com"
      },
      "OriginWarehouse": null,
      "DestinationWarehouse": {
        "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "name": "Bodega (Personaliza el nombre)",
        "code": null,
        "address": null,
        "description": null,
        "type": "warehouse",
        "phoneAreaCode": null,
        "phoneNumber": null,
        "latitude": 0,
        "longitude": 0,
        "openHours": null,
        "tags": null,
        "position": 1,
        "status": "created",
        "createdAt": "2019-01-30T17:18:46.000Z",
        "updatedAt": "2019-01-30T17:18:46.000Z",
        "CreatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "UpdatedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "LocationId": null,
        "TimezoneId": null,
        "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "SalesGroupId": null
      }
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "total_pages": 1,
    "current_page": 1,
    "next_page": 0,
    "previous_page": 0,
    "total_items": 2
  }
}

Equipo Integraciones API Multivende

En este artículo, te mostramos cómo cargar stock de tus productos mediante la API de Multivende.

En este artículo te mostramos cómo consultar el precio de tus productos mediante la API de Multivende.

La consulta de precios se realiza a productos asociados a una lista de precios en Multivende.

Consultar precios de productos.

Para obtener el id de una lista de precios consultamos al endpoint Get price lists.

Puedes consultar el precio de los productos que estén en una lista de precios mediante el endpoint Get prices with scroll, enviando:

• el id de la lista de precios
• límite de items a consultar (el rango del límite permitido es >=50 y <=5000)

Este endpoint permite obtener el precio de los productos paginados por scroll.

Para realizar el polling de precios lo puedes hacer consultando por un rango de fecha y hora, filtrando por el parámetro de fecha de creación (createdAt) o fecha de actualización (updatedAt). Esta modalidad es requerida para aquellas integraciones que realicen consultas frecuentes de precios, se recomienda que la ventana de búsqueda no sea mayor a 2 horas respecto a la última búsqueda realizada.

Equipo Integraciones API Multivende

Conoce las modalidades y operadores logísticos de los despachos que puedes gestionar a través de Multivende.

Modalidades logísticas

Podrás conseguir la información de las modalidades logísticas de tus despachos en los endpoints:

• Get checkouts light: Permite realizar el sondeo de las órdenes desde Multivende hacia tu integración.
• Get checkout: Ente endpoint te permite consultar el detalle de una orden.
• Get delivery order: Este Endpoint te permite consultar el detalle de un despacho asociado a una orden.

Delivery Order

En el detalle del DeliveryOrders:

• "shippingMode": Informa el modo de envío según lo que indica el canal de venta.
• "courierName": Informa el nombre del courier que realizará el despacho según lo que indica el canal de venta.

Checkout

En el detalle del Checkout:

• "shippingMode": Informa el modo de envío según lo que indica el canal de venta. En los casos donde hay más de un DeliveryOrder con diferentes ShippingMode, el campo indicará "multiple".
• "courierName": Informa el nombre del courier que realizará el despacho según lo que indica el canal de venta. En los casos donde hay más de un DeliveryOrder con diferentes courierName, el campo indicará "múltiple".
• "isMultiwarehouse": Informa si el punto de retiro del pedido para el despacho es más de uno.

Shipping Mode

En el "shippingMode" encontrarás las opciones propias de cada canal de venta, según la información que nos proporcione el canal vía API. (me1, me2, fulfillment, Dropshipping).

Ejemplo:

"shippingMode": "fulfillment",

courierName

En el “courierName” las opciones disponibles y denominación de los operadores logísticos podrán variar de acuerdo a la configuración propia del canal para identificar a cada uno (El courier Blue Express podrás encontrarlo con los valores: Blue Express, BLX, entre otros).

Ejemplo:

"courierName": "BLUEXPRESS",

Modalidades logísticas de los marketplaces:

Mercadolibre

Dafiti

Ripley 

Paris

Fcom (falabella.com)

Amazon 

Walmart

Coppel

Tik Tok Shop

T1

Totalplay

Éxito

Consideraciones para ventas con modalidad Fulfillment

Las ventas de tipo fulfillment pueden ser registradas en Multivende y leerse mediante la integración a través del endpoint de Get checkout, no hay diferencia entre el formato de estas ventas y otras modalidades.

Los canales de venta que tienen disponible esta modalidad son: Mercado Libre, Paris, Falabella.com, Amazon, Ripley y Walmart MX.

• Para activar el registro de las órdenes con esta modalidad logística debes habilitar la opción en la configuración de la conexión del canal como lo indica el artículo según el canal.
• Debido a que se crea una bodega especial para asociar las ventas fulfillment del marketplace, el stock de tus bodegas no se verá afectado.
• Para este tipo de órdenes el shippingMode trae el valor “fulfillment”, de esta manera se pueden identificar.
• Para Mercado Libre en Argentina, Colombia y México, el vendedor puede generar la factura.
• Para Mercado Libre Brasil y Chile, la factura es generada por Mercado Libre y el vendedor puede descargarla.

Equipo Integraciones API Multivende

Conoce el flujo mediante el cual puedes consultar las etiquetas de despacho via API.

El proceso de generación/consultas de etiquetas, debe realizarse consultado por cada Marketplace.

¿Cómo generar / consultar etiquetas de los Marketplace?

Te dejamos el paso a paso para que puedas obtener los documentos de despachos vía API:

1. Consultar las conexiones de los Marketplaces

Primero se debe consultar las conexiones de los Marketplaces que tiene habilitadas el Merchant por el endpoint Get Marketplace connections . El cual retorna un array con todas las conexiones, en el campo "_name" se indica el Marketplace al cual pertenece la conexión, los cuales pueden ser los siguientes:
 

Nota: Se deben descartar las conexiones de los Marketplace / Tiendas online que no están disponibles.

2. Consultar las órdenes disponibles para generar etiquetas

Con el "_Id" obtenido del respuesta anterior (Get Marketplace connections), se debe consultar por cada uno al Endpoint Get delivery orders with available labels. Enviando de forma predeterminada los siguientes parámetros:

• _delivery_statuses = "completed".
• _delivery_statuses = "pending".
• _shipping_label_print_statuses = "not_printed"
• _shipping_label_status = "ready"
• _include_only_delivery_order_with_traking_number = true
   

El response es un array paginado de 50 órdenes por página. Se debe iterar por cuantas paginas contenga.

CONSIDERACIONES ESPECIALES:

• Para generar las etiquetas de Linio y Dafiti es necesario cambiar el estado de la orden a "Listo para envío" previo a consultar las órdenes disponibles para generar etiquetas; por el endpoint Update delivery order status.
  • Para el caso de Falabella se puede generar la etiqueta sin previamente cambiar el estado a Listo para envío, pero se debe informar este estado al canal de venta para indicar que el despacho está listo.
• Para generar las etiquetas de Ripley debes realizar previamente la configuración indicada en el articulo Generación de etiquetas para Mercado Ripley hasta el paso 2, ya que los siguientes pasos son automatizados.
• Para generar las etiquetas de Walmart es necesario cambiar el estado de la orden a "En Manejo" previo a consultar las órdenes disponibles para generar etiquetas; por el endpoint Update delivery order status.
• Para generar las etiquetas de Liverpool es necesario cambiar el estado de la orden a "En Manejo" previo a consultar las órdenes disponibles para generar etiquetas; por el endpoint Update delivery order status.

3. Crear solicitud de generación de etiquetas

Con los _Id del response anterior (Get delivery orders with available labels), los cuales se pueden agrupar en un array de máximo 50 para consultar al endpoint PUT Generate delivery order tikets.. 

El cual crea una tarea asíncrona para procesar la solicitud de generar etiquetas.

Para verificar que la tarea esté procesada, consultar periódicamente al siguiente Endpoint Get bulk action task hasta que el campo "processStatus" sea ​​igual a:

• "completed",
• "completed_with_warnings"  
• "failed". 

En caso que sea "completed_with_warnings" o "failed" se debe volver a procesar la solicitud. 

Adicionalmente, se debe validar el valor del campo “output” en el se indica el estado de las órdenes a las que se le solicitó generar las etiquetas.

• "ordersWithAvailableDeliveryOrderTickets" es un array que contiene los id de las ordenes a las que se les puede generar etiqueta en la solicitud. Los campos que retorna son:
  •  
    •  "deliveryOrderId"
    • "deliveryOrderCode"
    • "checkoutId"
    • "checkoutCode"
    • "checkoutExternalId"
    • "deliveryOrderLinkId"
    • "deliveryOrderLinkExternalId"
• "ordersWithUnavailableDeliveryOrderTickets" es un array que contiene los id de las ordenes a las que no se les puede generar etiqueta en la solicitud.
• "failedDeliveryOrders" es un array que contiene los id de las ordenes a las que falló la generación de  etiquetas en la solicitud.
• "successfulDeliveryOrderDocuments" es un array que contiene los id de las ordenes a las que se les generó etiqueta en la solicitud. Los campos que retorna son:
  •  
    • "deliveryOrder"
    • "deliveryOrderId"
    • "deliveryOrderCode"
    • "checkoutId"
    • "checkoutCode"
    • "checkoutExternalId"
    • "deliveryOrderLinkId"
    • "deliveryOrderLinkExternalId"
    • "deliveryOrderDocumentId"
• "totalOrderProcessed" total de ordenes a las que se generó etiquetas en la solicitud.

Apartado especial para Multiboxing ( Disponible para Walmart y Liverpool) :

Cuando un pedido requiere varias cajas, Multivende permite generar múltiples guías de envío para un mismo despacho. A esta función se le llama Multiboxing.

Flujo recomendado para configurar tus cajas y generar múltiples etiquetas desde Multivende:

1. Obtén las dimensiones de los productos en tu despacho (opcional, si necesitas calcular manualmente tus cajas)

Puedes consultar las dimensiones de los productos incluidos en tu pedido usando el endpoint: 

Get Delivery Order in Checkout Items

Con esta información podrás aplicar la lógica que prefieras para determinar cuántas cajas necesitas y qué producto irá en cada una.

Este paso es opcional si ya cuentas con configuraciones previas o deseas usar cajas por defecto.

2. Consulta las cajas configuradas o las cajas por defecto (opcional) 

Multivende ofrece la opción de revisar las cajas que ya tengas registradas, o bien visualizar las cajas por defecto que aplicaremos cuando no edites la configuración, puedes hacer esta consulta mediente el endpoint Get Boxes

Si una caja corresponde a la configuración por defecto, verás el campo "default": true

3. Configura las cajas que utilizarás para este despacho

Una vez que tengas claro cómo vas a distribuir los productos, debes registrar las cajas necesarias para tu envío mediante el endpoint Post Boxes

Este endpoint recibe un array en el que debes indicar:

• Las dimensiones de cada caja (alto, ancho, largo, peso).

• Los productos asignados a cada caja.

Con esto, Multivende podrá generar las guías correspondientes de forma individual.

4. Cambia el estado de la orden para continuar con el proceso de despacho

Una vez configuradas las cajas, debes mover la orden al estado En manejo, lo que confirma que estás listo para generar las etiquetas. Esto lo hacemos actualizando el estado a la orden.

5. Genera las etiquetas de envío

Finalmente, puedes solicitar la generación de etiquetas tus cajas utilizando el flujo estándar de etiquetas en Multivende.

Consideraciones generales:

• Si hay órdenes que están en ""failedDeliveryOrders" o ""ordersWithUnavailableDeliveryOrderTickets" se deben volver a reprocesar.
• Si el valor de "totalOrderProcessed" no coincide con la cantidad de órdenes enviadas en la solicitud se debe a que hay ids de órdenes que no existen en Multivende enviadas para generar etiquetas.
• En caso de que alguna venta quede con error, se debe revisar con el Marketplace. 
• Se recomienda generar las etiquetas al apenas la integración validar que existe el stock y almacenar el PDF para su impresión, así disminuirán los tiempos en el proceso de packing.
• Por cada etiqueta los marketplace demorar aprox 1 min en poderla liberar.
• Para Amazon desde el momento en que se genere la url de los documentos de despacho desde el Get bulk action task, tienes 15 minutos para realizar la descarga y almacenarlo, la url caducará pasado el tiempo mencionado.
• En caso de que necesites descargar tus documentos de despacho de Amazon, si lo haces desde  Get delivery order consultando la url desde el deliveryOrderDocuments, esta url también tiene un tiempo de 15 minutos, pasado este tiempo la url caducará y deberás hacer nuevamente el llamado del endpoint para habilitar una nueva url.
• El proceso de generación masiva de etiquetas ha sido optimizado y estandarizado con el fin de controlar mayor cantidad de errores a la hora de generar etiquetas de despacho para los canales que utilizan esta función, el primer canal que ha implementado este funcionalidad estándar es Mercadolibre y próximamente lo hará Dafiti:

1.  
   1. La implementación de esta optimización no significa ni debiera significar cambio alguno en el proceso normal de generación de etiquetas para los canales, es decir no debiera haber diferencia en cómo el usuario veía antes las etiquetas y cómo las ve ahora. No obstante sí debiera notar un cambio a la hora de generar etiquetas que habían sido previamente generadas puesto que en el antiguo proceso no generábamos estas etiquetas.
   2. Actualmente cuando recibimos la solicitud para generar etiquetas previamente generadas (para el caso de Mercadolibre) lo que hacemos es tomarlas directamente desde el storage de Multivende (puesto que ya existen) generar el archivo consolidado y luego comprimirlas. Dichas etiquetas estarán disponibles con los mismos nombres de archivo pero, con la palabra “_old” al final de estos, esto con el fin de señalar que corresponden a etiquetas antiguas.
   3. Las etiquetas denominadas “_old” no contaran con archivos de control puesto que Multivende no genera este recurso por ser un recurso propio de Mercadolibre y por ser etiquetas antiguas el archivo de control ya estará asociado a otra generación masiva de etiquetas realizada previamente.
   4. Para este último caso el usuario podrá encontrar el archivo de control asociado a cada despacho individualmente.

El .zip contiene los siguientes archivos, según el formato que estableció el Marketplace:

• etiquetas para la impresora Zebra (SOLO MERCADO LIBRE - PARIS y FCOM*)
• manifiesto (SOLO MERCADO LIBRE, 1 manifiesto por solicitud)
• etiquetas en PDF
• Packing (agrupa los ítems por orden, formato Excel)
• Picking (agrupa todos los ítems de las órdenes, formato Excel)

*La activación del ZPL de FCOM se solicita directamente al canal de venta.

Documentos según canal de venta:

NOTA: si el Marketplace es Mercado Libre, automáticamente procesa la orden a lista, lo cual bloquea que se pueda cancelar por parte del cliente o Merchant.

No se registra que pueden pasar a buscar el pedido, esto se debe coordinar con el courier.

¿Cómo consultar las etiquetas de una orden?

A través del endpoint Get delivery order se puede consultar el detalle de entregas con despacho de una orden. El campo "DeliveryOrderDocuments" contiene un array con los documentos referentes a la entrega con despacho de la orden consultada.

Diagrama de Flujo 

A continuación, se encuentra el diagrama de flujo para las consultas.

Los cambios de estados lo puedes realizar mediante tu integración vía API, te explicamos a continuación. 

Puedes obtener el campo _id del endpoint Get checkout dentro del arreglo de DeliveryOrder, el cual es necesario para actualizar el estado de la entrega.

La actualización del estado se debe realizar según el tipo de entrega.

Despachos

Los siguientes datos pueden actualizarse por el endpoint Update delivery order status:

• "DeliveryOrderStatusId” = actualizar el estado del despacho según el _id correspondiente del endpoint Get Delivery Order Status
• "comment" = un comentario al despacho
• Para actualizar el número y url de tracking debes usar el endpoint Update delivery order
  • Los canales que permiten actualizar el número de tracking son los siguientes:
    • Mercadolibre (Esto aplica para envíos ME1, custom y not_specified).
    • Vtex (Aplica tanto para ordenes tipo "despacho" como "retiro en tienda").
    • Dafiti (Aplica para la modalidad "Dropshipping").
    • Amazon (Aplica para ventas de tipo Fulfillment - Channel == 'MFN').
    • Liverpool.

Tener en consideración que al enviar el cambio de estado a "Listo para envío" verificar posteriormente que este se haya sincronizado de forma correcta, esto lo pueden hacer consultando el Endpoint Get Delivery Order, el campo "DeliveryOrderStatusLink" verificando dentro de  "synchronizationStatus" el cual puede contener los siguientes estados:

Consideraciones Importantes:

• Si al pasar 10 minutos y se visualiza que no se ha realizado el cambio de estado, por favor enviar nuevamente la actualización de estado.
• Cuando se crea una tarea de cambio de estado, los campos del "DeliveryOrderStatusLink" serán informados en "null", cuando este cambio comience a ser procesado desde Multivende, el estado del campo "synchronizationStatus" informará uno de los 4 estados detallados en la tabla de arriba.
• En el caso de ME2 para los productos que registran tiempo de manufactura o fabricación, se debe actualizar el estado del despacho a "Listo para envío" posterior a la fecha en que se indicó que estaría el producto disponible.

Conoce la información de los estados de una de orden de acuerdo al tipo de entrega que maneje el vendedor.

Los estados de las órdenes dependen del tipo de entrega que haya seleccionado el cliente, por lo que puede variar según esta condición.

Tipos de entrega para una orden

Para obtener los diferentes tipos de entrega que puede tener una orden se debe consultar el Endpoint Get delivery types. Actualmente contamos con dos tipos de entrega posibles, las cuales, en el response de la solicitud se obtiene el campo code, que puede tener los siguientes valores:

1. “_delivery_type_delivery” = Despacho (el producto se envía a una dirección dada por el comprador).
2. "_delivery_type_store_pickup" = Retiro (el producto lo retira el comprador en la dirección de la bodega asociada al stock del producto).
3. "_delivery_type_mix" = Mixto (La orden está compuesta por varios productos de los cuales tiene retiro en tienda y despacho).

Entregas con despacho

En el endpoint Get Checkout entregamos información general del despacho, pero si necesitas información adicional como los documentos o logs de cambio de estado, consulta el endpoint Get delivery order.

Para realizar la integración con los sistemas, se debe hacer un mapeo de los estados de las órdenes en Multivende y el sistema con el que se va a integrar. Para ello, se consulta al endpoint Get Delivery Order Status el cual retorna un array con todos los estados posibles de una orden en Multivende. 

Del response se deben guardar los campos _id y code, que deben ser mapeados con los estados del sistema.

A continuación, se detallan los posibles estados de las ventas en Multivende y su relación con los estados de las ventas en los canales.

• Multivende

• Multivende - Amazon
  • Relación de estados entre Multivende y Amazon

• Multivende - Linio, Dafiti, Falabella
  • Relación de estados entre Multivende y Linio, Dafiti, Falabella

• Multivende - Mercado Libre 
  • Relación de estados entre Multivende y Mercado Libre

El estado solo se cambia en Mercadolibre para los pedidos que no son ME2 excepto el estado cancelado.

• Multivende - Paris
  • Relación de estados entre Multivende y Paris

• Multivende - Ripley
  • Relación de estados entre Multivende y Ripley

• Multivende - Walmart Chile
  • Relación de estados entre Multivende y Walmart Chile

• Multivende - Walmart México
  • Relación de estados entre Multivende y Walmart México 

• Multivende - Magento
  • Relación de estados entre Multivende y Magento

• Multivende - Shopify
  • Relación de estados entre Multivende y Shopify

• Multivende - VTEX 
  • Relación de estados entre Multivende y VTEX

Consideraciones especiales para la información logística por canal de venta

Cancelaciones parciales para el canal Paris:

Identificar los items cancelados: Para determinar qué artículo o artículos han sido cancelados en una orden de despacho, les instamos a buscar en el campo:

"checkoutLink" -> "externalContent" -> "subOrders "-> items al consultar la venta con Get checkout.

Dentro items, por cada uno de los items, en el campo “status” encontrarán la información detallada sobre la cancelación parcial en caso de que el ítem haya sido cancelado.

• Ejemplo:

"status": {
  "id": 31,
  "name": "stock_shortage_refunded",
  "description": "Reembolsado por falta de stock en la db",
  "translate": "Problema con stock",
  "cancelable": false
}

Estas indicaciones solo aplican para el caso del marketplace Paris. 

Equipo Integraciones API Multivende

Conoce la información de los estados de una orden de acuerdo al tipo de entrega “Retiro en tienda”.

Los estados de las órdenes pueden variar según el tipo de entrega seleccionado por el cliente.
En el caso de retiro en tienda, el flujo de la orden se ajusta a las etapas propias de este método, que van desde la preparación del pedido hasta su retiro en el punto de venta.

Tipos de entrega para una orden

Para obtener los diferentes tipos de entrega que puede tener una orden se debe consultar el Endpoint Get delivery types. Actualmente contamos con dos tipos de entrega posibles, las cuales, en el response de la solicitud se obtiene el campo code, que puede tener los siguientes valores:

1. “_delivery_type_delivery” = Despacho (el producto se envía a una dirección dada por el comprador).
2. "_delivery_type_store_pickup" = Retiro (el producto lo retira el comprador en la dirección de la bodega asociada al stock del producto).
3. "_delivery_type_mix" = Mixto (La orden está compuesta por varios productos de los cuales tiene retiro en tienda y despacho).

Entregas con retiro en tienda

En el endpoint Get Checkout entregamos información general del retiro en tienda, pero si necesitas información adicional como los documentos o logs de cambio de estado, consulta el endpoint Get pick up order.

Para realizar la integración con los sistemas, se debe hacer un mapeo de los estados de las órdenes en Multivende y el sistema con el que se va a integrar. Para ello, se consulta al endpoint Get pick up order statuses el cual retorna un array con todos los estados posibles de una orden en Multivende. 

Del response se deben guardar los campos _id y code, que deben ser mapeados con los estados del sistema.

A continuación, se detallan los posibles estados de las ventas en Multivende y su relación con los estados de las ventas en los canales.

• Multivende

• Multivende - Magento
  • Relación de estados entre Multivende y Magento

• Multivende - Mercado Libre 
  • Relación de estados entre Multivende y Mercadolibre

• Multivende - Liverpool 
  • Relación de estados entre Multivende y Liverpool

• Multivende - Shopify
  • Relación de estados entre Multivende y Shopify

• Si ya existe al menos un "fulfillment" (sin cancelación) el estado será: _pick_up_order_status_completed_

• Si no hay fulfillments dentro del pedido aún:

  • último fulfillment open → pick_up_order_status_pending

  • último fulfillment in_progress → pick_up_order_status_received_by_store

• Multivende - VTEX 
  • Relación de estados entre Multivende y VTEX

Actualizar el estado de una orden con retiro en tienda

Para actualizar el estado de una orden con retiro en tienda, lo hacemos mediante el endpoint: PUT Update pick up order status. 

Enviando en el body los siguientes parámetros:

"PickUpOrderStatusId": "{{pick_up_order_status_pending_id}}",
"comment": "test comment",
"pickUpClosingComment": "test Pick Up Closing Comment",
"estimatedPickUpDateFrom": "2019-09-08 16:19:06",
"estimatedPickUpDateTo": "2019-09-10 09:19:06",
"effectivePickUpClosingDate": "2019-09-11 16:19:06"

Equipo Integraciones API Multivende

¿Cuándo es útil Multiboxing?

Multiboxing te permite dividir un pedido en varias cajas, asignando a cada una su propia guía de rastreo. Así puedes dar seguimiento individual a cada paquete, tanto tú como tu cliente.
Esta opción es especialmente útil cuando:

• El producto no cabe en una sola caja.
• El pedido incluye varias piezas grandes o voluminosas.
• La paquetería exige separar los productos por peso o dimensiones.
• Deseas optimizar costos o tiempos de entrega distribuyendo mejor el contenido.
   

¿Cómo configurar Multiboxing paso a paso?

A continuación te mostramos el flujo recomendado para configurar tus cajas y generar múltiples etiquetas desde Multivende.

1. Obtén las dimensiones de los productos en tu despacho (opcional, si necesitas calcular manualmente tus cajas)

Puedes consultar las dimensiones de los productos incluidos en tu pedido usando el endpoint:

👉 Get Delivery Order in Checkout Items
GET /delivery-order/checkout-items - Ver endpoint en Postman

Con esta información podrás aplicar la lógica que prefieras para determinar cuántas cajas necesitas y qué producto irá en cada una.

Este paso es opcional si ya cuentas con configuraciones previas o deseas usar cajas por defecto.

2. Consulta las cajas configuradas o las cajas por defecto

Multivende ofrece la opción de revisar las cajas que ya tengas registradas, o bien visualizar las cajas por defecto que aplicaremos cuando no edites la configuración.

👉 Get Boxes
GET /boxes - Ver endpoint en Postman

Si una caja corresponde a la configuración por defecto, verás el campo:

"default": true

3. Configura las cajas que utilizarás para este despacho

Una vez que tengas claro cómo vas a distribuir los productos, debes registrar las cajas necesarias para tu envío.

👉 Post Boxes
POST /boxes - Ver endpoint en Postman

Este endpoint recibe un array en el que debes indicar:

• Las dimensiones de cada caja (alto, ancho, largo, peso).
• Los productos asignados a cada caja.
   

Con esto, Multivende podrá generar las guías correspondientes de forma individual.

4. Cambia el estado de la orden para continuar con el proceso de despacho

Una vez configuradas las cajas, debes mover la orden al estado En manejo, lo que confirma que estás listo para generar las etiquetas.

Guía relacionada:
🔗 Estados de una orden con despacho

5. Genera las etiquetas de envío

Finalmente, puedes solicitar la generación de etiquetas tus cajas utilizando el flujo estándar de etiquetas en Multivende.

Guía relacionada:
🔗 Cómo generar y consultar etiquetas de los Marketplace

Certificación ISO 27001 - Conoce más sobre la certificación de Multivende.

Multivende ha obtenido la certificación ISO 27001, la norma internacional que garantiza las mejores prácticas en gestión de la seguridad de la información. Esta certificación reconoce nuestro compromiso con la protección de los datos y la gestión de la seguridad en todos nuestros procesos.

La ISO 27001 se centra en identificar y gestionar los riesgos relacionados con la información, estableciendo un marco robusto para proteger la confidencialidad, integridad y disponibilidad de los datos. Con esta certificación, aseguramos que nuestros sistemas y procedimientos cumplen con los más altos estándares de seguridad, brindando confianza tanto a nuestros clientes como a nuestros socios comerciales.

Nuestro equipo trabaja continuamente para mantener estos estándares, implementando políticas y controles que garantizan la seguridad en cada etapa de nuestro trabajo.

Equipo Integraciones API Multivende

Consulta la información asociada a los procesos de privacidad e integridad de los datos de nuestra API.

• Todas las interacciones con la API de Multivende deben realizarse usando https.
• Será responsabilidad de Multivende actualizar el certificado correspondiente cuando este vaya a expirar.
• Será responsabilidad de quién consuma la API realizar todas las llamadas utilizando https con la versión de TLS> = 1.2. Para detalles del certificado se puede usar openssl en el terminal: 

echo | openssl s_client -showcerts -servername app.multivende.com 
-connect app.multivende.com:443 2/dev/null | openssl x509 -inform pem -noout –text

Conoce los rangos de IPs utilizados por Multivende en esta información detallada.

Sigue nuestras recomendaciones para garantizar la seguridad de tu integración.

Encriptación de datos:

• Es necesario encriptar el token y el refresh token utilizando un algoritmo de clave simétrica antes de almacenarlos en la base de datos.

Ventajas del uso de una IP estática a nivel de seguridad:

• Identificación confiable: Una IP estática te permite identificar de manera consistente a tu contraparte porque siempre tendrá la misma dirección IP. Esto puede facilitar la implementación de controles de acceso basados en IP (por ejemplo, listas blancas).
• Mayor control sobre la seguridad de la red: Como puedes predecir de dónde vendrán las peticiones, es posible configurar firewalls y reglas específicas para esa IP, lo que añade una capa adicional de seguridad.
• Riesgo de exposición: Si alguien malintencionado descubre esa IP estática, podría intentar atacarla directamente. Sin embargo, si la comunicación está protegida por HTTPS, el cifrado de la conexión protegerá los datos en tránsito.

Equipo Integraciones API Multivende

En este artículo, te compartimos algunas recomendaciones para realizar tu integración vía API con Multivende.

Si debes crear una integración porque formas parte de nuestro Developers Partners Program o si ya te encuentras trabajando en una integración para un merchant de Multivende, debes seguir las siguientes recomendaciones para que puedas brindar la mejor experiencia de trabajo al merchant y para que tus procesos también sean más optimizados.

Desarrollo de integraciones como Partner de Multivende

Si eres miembro de nuestro Developers Partners Program como desarrollador de integraciones con Multivende, debes tomar en cuenta las siguientes recomendaciones:

Consideraciones como desarrollador:

• Debes asegurarte de que tu equipo de desarrollo asista al onboarding de TI, ya que en este se dejará configurada la cuenta test del merchant para las pruebas en ambiente QA de la integración.

• Como integrador debes asistir a las reuniones semanales pautadas durante el proyecto de integración.

• Te pedimos que seas muy claro en las funcionalidades que cubre tu integración, las cuáles debes notificarnos en el Go Live y dejar definido si es factible realizar algún desarrollo customizado que el merchant requiera.

Consideraciones de parte de Multivende:

• Nuestro equipo de API hará seguimiento para confirmar la finalización del proyecto, es importante que des respuesta a nuestros emails y realizar una reunión para validar que la integración finalizó con éxito.

• Recuerda que ante cualquier duda o inconveniente en la conexión con nuestro servicio de integraciones, puedes consultarnos a través del correo electrónico api@multivende.com.

Desarrollo de integraciones para clientes

Si ya te encuentras desarrollado una integración específica para un merchant de Multivende, debes tomar en cuenta las siguientes recomendaciones

Consideraciones como desarrollador:

• Una vez cerrado tu acuerdo comercial, mantén en todo momento la comunicación, es importante que vayas dando estatus de los avances de la integración y asistir a todas a las reuniones pautadas.
  Recuerda que si requieres apoyo del equipo de API de Multivende puedes avisarnos y sumarnos a la comunicación.
• Debes ser claro en las funcionalidades que cubre tu integración y deja definido si es factible realizar algún desarrollo customizado que el merchant requiera.
• Debes llenar el formulario de integraciones en conjunto con el merchant cuando el equipo de Onboarding lo solicite para definir el alcance de la integración previo al kickoff.

• Como integrador, debes asistir a las reuniones semanales pautadas durante el proyecto de integración.

• Debes solicitar al merchant directamente los accesos a sus cuentas productivas en Multivende y gestionar las pruebas y recursos necesarios para validar la integración.

• Debes asegurarte de que tu equipo de desarrollo asista al onboarding de TI donde se deja configurada la cuenta test de merchant para las pruebas en ambiente QA de la integración. 

• Como integrador, debes garantizar que la integración cumpla con las necesidades del merchant.

Consideraciones de parte de Multivende:

• Multivende es responsable de realizar el kickoff inicial del proyecto para un merchant en conjunto. Como integrador, debes asistir a esta reunión con los miembros de tu equipo de TI que realizará la integración, ya que en el kickoff se debe dejar claro el alcance del proyecto.

• Nuestro equipo de API hará seguimiento para confirmar la finalización del proyecto, es importante que des respuesta a nuestros emails y realizar una reunión para validar que la integración finalizó con éxito.

• Recuerda que ante cualquier duda o inconveniente en la conexión con nuestro servicio de integraciones puedes consultarnos a través del correo electrónico api@multivende.com.

¡Manténte atento a las comunicaciones API!

Te aconsejamos estar atento a las comunicaciones de nuestro equipo de desarrollo ante cualquier comunicación que enviemos referente a la actualización en nuestra API, esto con el fin de garantizar que tu desarrollo no se vea afectado ante algún cambio.

Equipo Integraciones API Multivende

Necesitas el Client ID y Secret para obtener un token y acceder a los servicios de nuestra API.

Debes ingresar en tu cuenta previamente creada realizando login a través de:

• https://app.multivende.com/developers/login

Tanto el Client ID como el Client Secret los puedes encontrar ingresando a tu lista de aplicaciones.

Haz click en el botón de acciones como se muestra en la siguiente imagen:

Al darle click al botón de acciones podrás editar los datos de tu aplicación, además, en la parte superior del formulario encontrarás el Client ID y el Client Secret resaltado en color azul.

Equipo Integraciones API Multivende

El Merchant ID es clave para consultas en la API. Aquí aprenderás a ubicarlo en la interfaz.

• Para consultar tu ID de comerciante, debes seguir los pasos a continuación:

1.- Debes hacer clic en el ícono del lápiz que aparece al lado del nombre de la cuenta. Este enlace te llevará a visualizar/editar los datos de la cuenta.

2.- Toma de la URL el ID, este es el identificador de la cuenta (Merchant_id).

¡Listo! Ya obtuviste tu Merchant ID.

Equipo Integraciones API Multivende

Aprende a consultar los ID de recursos en la interfaz de la plataforma Multivende.

Para facilitar la visibilidad entre los ID entregados vía API y la plataforma, en la URL de Multivende puedes verificar el ID del ítem seleccionado.

Por ejemplo, al seleccionar "editar" una bodega la URL será:

https://app.multivende.com/stores-and-warehouses/XXXXXXXX-3639-4c28-9e1c-XXXXXXXXXXXX/edit

Donde el ID correspondiente a la bodega es: XXXXXXXX-3639-4c28-9e1c-XXXXXXXXXXXX.

Equipo Integraciones API Multivende

Este campo es el identificador único de una conexión con un canal de venta de la cuenta de un merchant.

Puedes consultar la información de este Id para las conexiones de las cuentas de un merchant mediante el endpoint Get Marketplace connections  , la api retornará un array con todas las conexiones disponibles en la cuenta del merchant:

{
  "entries": [
    {
      "_name": "Mercadolibre",
      "_id": "a58xxxe-1fb6-4bd2-80xx-1b795xxxa39a",
      "name": null,
      "country": "cl",
      "pictureUrl": "https://s3.amazonaws.com/im-shared/mercadolibre.png",
      "provider": "mercadolibre",
      "allowPickUpInStore": null
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "total_pages": 1,
    "current_page": 1,
    "next_page": 0,
    "previous_page": 0,
    "total_items": 1
  }
}

En el request de la solicitud se debe identificar el canal de venta al que estamos consultando las conexiones.

Marketplace

• mercadolibre
• linio
• dafiti
• ripley
• paris
• fcom
• amazon
• walmart
• coppel

Online Store:

• vtex
• magento
• shopify
• prestashop
• wocommerce
• jumpseller
• bigcommerce

Equipo Integraciones API Multivende

Si tienes problemas con Webhooks, revisa varios factores que pueden afectar su funcionamiento.

A continuación, se detallan algunas posibles causas y soluciones para que puedas realizar las validaciones necesarias.

1. Enviar CallbackURL para realizar validaciones internas

• Una de las primeras acciones que debes tomar es asegurarte de que la URL de devolución (CallbackURL) esté correctamente configurada. Esta URL es crucial para que el servidor receptor pueda validar las solicitudes de Webhook. Asegúrate de que la CallbackURL esté configurada correctamente en tu aplicación y que esté preparada para recibir y procesar los Webhooks de manera adecuada.

2. El problema puede ser porque no está permitiendo la IP de Multivende

• Otro posible motivo por el que no recibes los Webhooks es que tu servidor no esté permitiendo la IP de Multivende (o el servidor que está enviando los Webhooks).
• Si tu firewall o configuración de red bloquea estas direcciones IP, los Webhooks no podrán llegar correctamente.
• Verifica que las direcciones IP de origen estén permitidas en tu servidor para asegurarte de que el tráfico de los Webhooks no sea bloqueado.

3. CallbackURL sin certificado SSL válido

• Una de las razones más comunes por las cuales los Webhooks no se reciben es un problema con el certificado SSL de la CallbackURL. Si la URL de destino no tiene un certificado SSL válido o si no está configurada para aceptar conexiones seguras (https), los Webhooks pueden ser rechazados por motivos de seguridad.
• Asegúrate de que tu servidor tenga un certificado SSL válido y que la URL de Callback sea accesible a través de HTTPS.

4. Tiempo de procesamiento de la solicitud muy alto (> 2 segundos)

• El tiempo de procesamiento de la solicitud también puede ser un factor importante. Si el procesamiento de la solicitud que recibes en el Webhook demora más de 2 segundos, es posible que el sistema de Webhooks no lo registre correctamente o que el Webhook se agote por tiempo de espera.
• Revisa el rendimiento de tu servidor y asegúrate de que las solicitudes se procesen de manera eficiente y en tiempos adecuados para evitar problemas.

Conclusión

Si estás experimentando problemas con la recepción de Webhooks, asegúrate de validar cada uno de los puntos mencionados anteriormente. Revisar la configuración de la CallbackURL, permitir las IPs correctas, contar con un certificado SSL válido y optimizar el tiempo de procesamiento de las solicitudes te ayudará a resolver los inconvenientes y mejorar el flujo de trabajo con Webhooks.

Si después de verificar estos puntos el problema persiste, puede ser útil realizar pruebas adicionales y revisar los logs de tu servidor para obtener más información sobre el origen del problema.

¿Necesitas ayuda con la API? Crea un ticket y el equipo de Integraciones te asistirá pronto.

Paso 1: Accede a la Plataforma de Soporte

Lo primero que debes hacer es ingresar a la plataforma de soporte o al sistema de tickets de Multivende. Este acceso se encuentra en la sección de Soporte o Ayuda de nuestro sitio web o dentro de la misma aplicación.

• Desde la web: Dirígete a la página de soporte, encontrarás la opción "Enviar una solicitud"

• Desde la aplicación: Si estás trabajando en nuestra plataforma, busca la opción "Crear ticket de ayuda" en el menú principal.

Paso 2: Selecciona la Categoría Correcta

Una vez que hayas ingresado al sistema de soporte, deberás elegir la categoría adecuada para tu solicitud. En este caso, selecciona "Necesito crear un ticket de soporte para integraciones API" que te llevará directamente al formulario de tickets relacionado con este tema.

Paso 3: Completa el Formulario de Ticket

El siguiente paso es completar el formulario con los detalles de tu solicitud. Asegúrate de proporcionar la mayor cantidad de información posible para que el equipo de Integraciones pueda ayudarte de manera eficiente.

Los campos más comunes en el formulario incluyen:

• Correo electrónico: Escribe el correo en donde te enviaremos la confirmación de la creación de tu solicitud y en donde podrás realizar el seguimiento.
• Nombre y Apellido: De la persona que está creando la solicitud.
• Asunto del ticket: Escribe un resumen breve y claro de tu solicitud o problema.
• Nombre de la empresa: Nombre de la empresa que realiza la integración más el nombre del equipo integrador.
• Sistema que estás integrando: Indicados el sistema, ya sea ERP, OMS, etc...
• Descripción detallada: Explica detalladamente el problema que estás enfrentando, la duda que tienes o el tipo de asistencia que necesitas. Incluye cualquier error o mensaje que hayas recibido, así como el contexto de tu integración (por ejemplo, versión de la API, pasos que seguiste, etc.).
• Información adicional: Podrás adjuntar archivos como capturas de pantalla, logs de errores, ejemplos de código, etc. Estos detalles ayudarán al equipo a entender mejor el problema.

Paso 4: Enviar el Ticket

Una vez que hayas completado el formulario y revisado toda la información, haz clic en el botón de Enviar para crear el ticket. Esto enviará tu solicitud directamente al equipo de Integraciones vía API.

Paso 5: Espera la Confirmación y Respuesta

Después de enviar el ticket, recibirás un correo de confirmación con el número de seguimiento del ticket. El equipo de Integraciones comenzará a trabajar en tu solicitud y se pondrá en contacto contigo para proporcionarte una solución o más detalles si fuera necesario.

• Tiempo de respuesta: El tiempo de respuesta puede variar dependiendo de la complejidad de la solicitud, pero el equipo de Integraciones se compromete a responder lo antes posible.

Paso 6: Cerrar el Ticket

Una vez que se haya resuelto tu solicitud y estés satisfecho con la solución, se procederá a cerrar el ticket. Si en algún momento tienes más preguntas o problemas adicionales, puedes abrir un nuevo ticket en cualquier momento.

Consejos para Crear un Ticket Eficaz

• Sé claro y preciso: Cuanto más detallada sea la información que proporciones, más fácil será para el equipo de Integraciones ayudarte.
• Incluye ejemplos y código: Si estás enfrentando un problema técnico, incluir fragmentos de código, logs o capturas de pantalla puede ayudar a que se resuelva más rápidamente.
• Prioriza la solicitud: Si el problema es urgente, asegúrate de marcarlo con la prioridad más alta para que el equipo pueda darle atención inmediata.

Equipo de integraciones API Multivende.