Ventas

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

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

Modos de consulta según funcionalidad a integrar

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

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, es decir: "YYYY-mm-dd hh:mm:ss".

Ejemplo:

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

curl --location -g '{{base_url}}/api/m/{{merchant_id}}/checkouts/light/p1?_updated_at_from=2020-03-18%2018%3A30&_updated_at_to=2020-03-18%2020%3A30' \

--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"
    }
  ],
  "paginación": {
    "desplazamiento": 0,
    "limit": 50,
    "total_pages": 1,
    "current_page": 1,
    "next_page": 0,
    "previous_page": 0,
    "total_items": 11
  }
}

Recomendamos registrar en su sistema los campos updatedAt (Fecha de última actualización en Multivende), soldAt (Fecha de la venta en el canal), y "_id" (identificador de la venta 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.

Cuando el response tiene el campo:

• DeliveryOrdersInCheckouts: Se refiere a la venta con despachos, el cual es un arreglo que detalla toda la información de los despachos de la venta.
  • Cada despacho viene dentro de un objeto que se llama DeliverOrder. En el objeto se encuentra la dirección de despacho dentro del objeto ShippingAddress.

• 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.
• Los webhooks se deben complementar con un polling para disminuir la probabilidad de pérdida de datos. (Actualmente no estamos realizando re intentos que aseguren el delivery de la notificación).
• Si al consultar el detalle de la venta con el CheckoutId el response es con status 404, se debe a que se trata de una venta que presentó error en el registro de Multivende la cual no queda registrada.
• Deben validar siempre desde webhooks y polling que el id de la venta informado ya se encuentre registrado en tu sistema para ver si la creas o actualizas.
• Validar para actualizar si la fecha de updateAt es diferente a la que tienes registrada.

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"
    }
  ]
}

Si se consultan los id's asociados a las ventas con error en la api de Get checkout esta dará un 404 debido a que las ventas con error no quedan guardadas en Multivende.

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",
    "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: "false", 
}

Mercadolibre

Se informa dentro de "remote_order_extra_billing_information --> "billing_info" --> "additional_info"

Si la orden de compra en una boleta llegará de la siguiente manera:

{
  "type": "INVOICE_TYPE",
  "value": "Boleta"
},

Y en caso de ser factura:

{
  "type": "INVOICE_TYPE",
  "value": "Factura"
},

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

Conoce cómo configurar atributos personalizados a una venta a través de la API.

Grupos de atributos personalizados para las ventas:  A través de la API de Multivende puedes crear, editar o consultar estos grupos de atributos personalizados.

• Consultar grupos de atributos: mediante el endpoint de Get Custom Attribute Sets puedes realizar la consulta de los grupos de atributos personalizados de ventas asociados a una cuenta de merchant.
• Crear un grupo de atributos: puedes crear un grupo de atributos via API mediante el endpoint Post Custom Attribute Sets  
• Editar un grupo de atributos: la actualización de un grupo de atributos se hace por medio del endpoint Put Custom Attribute Sets

Atributos personalizados para las ventas: los atributos se crean dentro un grupo. A través de la API de Multivende puedes crear, editar o consultar estos atributos personalizados.

• Consultar atributos: mediante el endpoint de Get Checkouts Custom Attributes puedes realizar la consulta de atributos personalizados de una venta para que puedas registrarlos o leerlos mediante tu integración.
• Crear un atributo: puedes crear un atributo dentro de un grupo de atributos via API mediante el endpoint Post Chekouts Custom Attributes   
• Actualizar un atributo: puedes actualizar la información de un atributo personalizado de la venta a través del endpoint Put Checkout Custom Attributes