Este método retorna las ventas de los distintos canales de venta que fueron capturadas por Ventiapp. El órden con el que se muestran es por fecha de creación de modo decreciente (la más nueva se verá primero). Esta API se puede consumir como máximo 1 ocurrencia por segundo.
Para encontrar alguna venta el parámetro date es obligatorio.
Query Parameters
Name
Type
Description
Headers
Name
Type
Description
{"paging": 50,"offset": 0,"total": 2,"sort": "added_desc","results": [ {"orderId":1234,"channel":"amazon","dateAdded":"2018-10-29T00:00:00","dateCreated":"2018-10-29T00:00:00","dateModified":"2018-10-29T00:00:00","externalId":"111444123","total":660.0,"currency":"MXN","tax":0.16,"comments":"Send it before tuesday",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"itemsQuantity":2,"title":"Order Title","internalStatus":1,"amazonFulfillment":"MFN","cartId":"00000101110002",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"externalNumber":"12314512","orderStatus":"paid","Discounts":120.00,"items": [ {"itemExternalId":"MLM3312341","title":"Item 1","price":460.0,"variationId":"13818313",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"variationName":"Red",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"itemQuantity":1,"total":460.0,"sku":"ITEM-RED001",//SKU DE VENTIAPP"channelSku":"765840000",//SKU DEL CANAL"erpId":null,//INFORMACION OPCIONAL (SOLO PARA INTEGRACIONES CUSTOM)"itemStatus":"returned"//INFORMACION OPCIONAL (DEPENDE DEL CANAL) }, {"itemExternalId":"MLM3317841","title":"Item 2","price":200.0,"variationId":null,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"variationName":null,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"itemQuantity":1,"total":200.0,"sku":"PLAINITEM001",//SKU DE VENTIAPP"channelSku":"765840001",//SKU DEL CANAL"erpId":null,//INFORMACION OPCIONAL (SOLO PARA INTEGRACIONES CUSTOM)"itemStatus":null//INFORMACION OPCIONAL (DEPENDE DEL CANAL) } ],"buyer": {"name":"John",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"lastname":"Doe",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"email":"email@api.com",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"state":"Distrito Federal",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"address":"Street Address 123",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"city":"Mexico City",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"zipcode":"06700",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"nickname":"JOHNDOEVENTI",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"phone":"5584848152",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"externalId":"551331413",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"municipality":"cuahutemoc",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"neigborhood":"roma sur",//INFORMACION OPCIONAL (DEPENDE DEL CANAL),"Comments":"Dejar al lado de la puerta","billingInfo": { //INFORMACION FISCAL OPCIONAL(DEPENDE DEL CANAL)"docType":"DNI","docValue":"123456789" } },"shipping": {"sellerInfo":"MYSELLERNAME",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"sellerId":null,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shipmentType":"me2",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingStatus":"shipped",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingCourier":"drop_off",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingId":"27586098188",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingType":"me2",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"ventiShipping":false,"ventiCourierId":null,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingTrackingId":"10003313132",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingCourierExternal":"Fedex Express",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingCost":120.0,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingReceptor":"Juan Dominguez",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"ShippingRealCost":23.4 },"paymentMethods": [ //INFORMACION OPCIONAL (DEPENDE DEL CANAL) {"externalId":"5531048951","paymentMethod":"oxxo" } ],"accountName":"MY_MELI_USER" }, {"orderId":1234,"channel":"meli","dateAdded":"2018-10-29T00:00:00","dateCreated":"2018-10-29T00:00:00","dateModified":"2018-10-29T00:00:00","externalId":"111444124","total":660.0,"currency":"MXN","tax":0.16,"comments":"Send it before tuesday",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"itemsQuantity":2,"title":"Order Title 2","internalStatus":1,"amazonFulfillment":null,"cartId":"00000101110007",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"orderStatus":"paid","items": [ {"itemExternalId":"MLM3312341","title":"Item 1","price":460.0,"variationId":"13818313",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"variationName":"Red",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"itemQuantity":1,"total":460.0,"sku":"ITEM-RED001",//SKU DE VENTIAPP"channelSku":"765840000",//SKU DEL CANAL "erpId":null,//INFORMACION OPCIONAL (SOLO PARA INTEGRACIONES CUSTOM)"itemStatus":null//INFORMACION OPCIONAL (DEPENDE DEL CANAL) }, {"itemExternalId":"MLM3317841","title":"Item 2","price":200.0,"variationId":null,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"variationName":null,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"itemQuantity":1,"total":200.0,"sku":"PLAINITEM001",//SKU DE VENTIAPP"channelSku":"765840001",//SKU DEL CANAL"erpId":null,//INFORMACION OPCIONAL (SOLO PARA INTEGRACIONES CUSTOM)"itemStatus":null//INFORMACION OPCIONAL (DEPENDE DEL CANAL) } ],"buyer": {"name":"John",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"lastname":"Doe",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"email":"email@api.com",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"state":"Distrito Federal",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"address":"Street Address 123",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"city":"Mexico City",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"zipcode":"06700",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"nickname":"JOHNDOEVENTI",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"phone":"5584848152",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"externalId":"551331413",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"municipality":"cuahutemoc",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"neigborhood":"roma sur",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"billingInfo":null//INFORMACION FISCAL OPCIONAL(DEPENDE DEL CANAL) },"shipping": {"sellerInfo":"MYSELLERNAME",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"sellerId":null,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shipmentType":"me2",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingStatus":"shipped",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingCourier":"drop_off",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingId":"27586098188",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingType":"me2",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"ventiShipping":false,"ventiCourierId":null,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingTrackingId":"10003313132",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingCourierExternal":"Fedex Express",//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingCost":120.0,//INFORMACION OPCIONAL (DEPENDE DEL CANAL)"shippingReceptor":"Juan Dominguez"//INFORMACION OPCIONAL (DEPENDE DEL CANAL) },"paymentMethods": [ //INFORMACION OPCIONAL (DEPENDE DEL CANAL) {"externalId":"5531048951","paymentMethod":"oxxo""paymentStatus": "accepted" } ],"accountName":"MY_MELI_USER" } ]}
Las opciones válidas para el parámetro de sort son:
added_desc : Fecha de Alta en VentiApp descendiente
added_asc: Fecha de Alta en VentiApp ascendiente
created_desc: Fecha de creación inicial de la compra descendiente
created_asc: Fecha de creación inicial de la compra ascendiente
modified_desc: Fecha de modificación de la compra descendiente
modified_asc: Fecha de modificación de la compra ascendiente
Channels
Las opciones válidas para el parámetro channel son:
Este método busca una venta en específico, o un carrito con órdenes asociadas.
Query Parameters
{"paging": 50,"offset": 0,"total": 1,"sort":null,"results": [ {"orderId":1234,"channel":"meli","dateAdded":"2018-10-29T00:00:00","dateModified":"2018-10-29T00:00:00","externalId":"111444123","total":660.0,"currency":"MXN","tax":0.16,"comments":"Send it before tuesday","itemsQuantity":2,"title":"Order Title","internalStatus":1,"amazonFulfillment":"false","cartId":"00000101110002","externalNumber":"12314512","orderStatus":"paid","Discounts":120.00,"items": [ {"itemExternalId":"MLM3312341","title":"Item 1","price":460.0,"variationId":"13818313","variationName":"Red","itemQuantity":1,"total":460.0,"sku":"ITEM-RED001",//SKU DE VENTIAPP"channelSku":"765840002",//SKU DEL CANAL"erpId":null,"itemStatus":"returned" }, {"itemExternalId":"MLM3317841","title":"Item 2","price":200.0,"variationId":null,"variationName":null,"itemQuantity":1,"total":200.0,"sku":"PLAINITEM001",//SKU DE VENTIAPP"channelSku":"765840001",//SKU DEL CANAL"erpId":null,"itemStatus":null } ],"buyer": {"name":"John","lastname":"Doe","email":"email@api.com","state":"Distrito Federal","address":"Street Address 123","city":"Mexico City","zipcode":"06700","nickname":"JOHNDOEVENTI","phone":"5584848152","externalId":"551331413","municipality":"cuahutemoc","neigborhood":"roma sur","Comments":"Dejar al lado de la puerta","billingInfo": { //INFORMACION FISCAL OPCIONAL(DEPENDE DEL CANAL)"docType":"DNI","docValue":"123456789" } },"shipping": {"sellerInfo":"MYSELLERNAME","sellerId":null,"shipmentType":"me2","shippingStatus":"shipped","shippingCourier":"drop_off","shippingId":"27586098188","shippingType":"me2","ventiShipping":false,"ventiCourierId":null,"shippingTrackingId":"10003313132","shippingCourierExternal":"Fedex Express","shippingReceptor":"Juan Dominguez","ShippingRealCost":23.4 },"paymentMethods": [ {"externalId":"5531048951","paymentMethod":"oxxo" } ],"accountName":"MY_MELI_USER" } ]}
Este método es utilizado para crear una orden en Ventiapp
{"paging":1,"offset":0,"total":1,"sort":null,"searchDateBy":null,"results": [ {"orderId":16491779,"channel":"ventiapp","dateAdded":"2023-03-07T23:29:11","dateModified":"2023-03-07T23:29:11","dateCreated":"2023-03-07T23:29:11","externalId":"16491779","externalNumber":null,"total":599.9700,"currency":null,"tax":82.7500,"discounts":null,"comments":null,"itemsQuantity":3,"title":"Chamarra de Algodón","internalStatus":0,"orderStatus":"paid","amazonFulfillment":null,"cartId":null,"items": [ {"itemExternalId":null,"title":"Chamarra de Algodón","price":199.9900,"sellPrice":null,"variationId":null,"variationName":null,"itemQuantity":2,"total":399.9800,"sku":"AA123-GREEN-M","skuChannel":"AA123-GREEN-M","erpId":"","fulfilled":false,"itemStatus":null,"itemFee":null,"itemType":null,"taxCode":null,"taxUnit":null }, {"itemExternalId":null,"title":"Artículo de prueba","price":199.9900,"sellPrice":null,"variationId":null,"variationName":null,"itemQuantity":1,"total":199.9900,"sku":"TestArticulo1","skuChannel":"TestArticulo1","erpId":null,"fulfilled":false,"itemStatus":null,"itemFee":null,"itemType":null,"taxCode":null,"taxUnit":null } ],"buyer": {"name":"Jaime","lastname":null,"email":"jaime_email@api.com","state":"Distrito Federal","address":"Street Address LT 123","address2":null,"street":null,"externalNumber":null,"internalNumber":null,"city":"Distrito Federal","zipcode":"06700","nickname":null,"phone":"5584848152","municipality":null,"neighborhood":null,"externalId":null,"companyBuyer":null,"billingInfo":null,"additionalField1":null,"additionalField2":null,"comments":null },"shipping": {"sellerInfo":null,"sellerId":null,"shipmentType":null,"shippingStatus":null,"shippingCourier":null,"shippingId":null,"shippingType":null,"ventiShipping":false,"ventiCourierId":null,"shippingTrackingId":null,"shippingCourierExternal":null,"shippingCost":null,"fulfillment":"dropshipping","shippingReceptor":null,"country":"México","shippingDiscount":null,"shippingCostPromo":null,"clientCouponAmount":null },"paymentMethods": [],"accountName":null,"externalErpId":null,"externalStatus":"paid" } ]}
Body de la llamada:
{"Buyer": {// Campos obligatorios"Name":"Jaime",// Si el cliente es nuevo, es obligatorio este campo"RFC":"JAIME940208KPB","Email":"jaime_email@api.com","BusinessName":"None",// Si el cliente es nuevo, es obligatorio este campo// Campos opcionales"Zipcode":"06700","Phone":"5584848152","State":"Distrito Federal","Street":"Street Address 123","Municipality":"Distrito Federal","Population":"Street Address LT 123","Suburb":"Morelos","ExternalNumber":"123","InternalNumber":"12" },"Products": [ {"Sku":"AA123-GREEN-M","Quantity":2 }, {"ProductID":5236732,"Quantity":1 } ]}
Este método es utilizado para imprimir la guía asociada a la venta. Cuando se imprime la guía por primera vez, el marketplace asociado avisará al cliente que el pedido se está procesando en automático, es por eso que recomendamos verificar este proceso antes de una implementación en un sistema automatizado.
El externalId, ó el orderId son obligatorios, con uno de los dos ya es válida la llamada
El campo type es opcional, en este se tiene que indicar si es zpl o pdf (No todos los canales soportan ZPL, Ventiapp está trabajando para realizar la conversión). El valor por defecto es pdf
Canales implementados:
- Guías generadas desde Ventiapp (ej: EnviaYa, Skydropx o paquetería propia)- Mercado Libre
- Mercado Shops
- Linio
- Claroshop
- Amazon (en desarrollo)
- Walmart (en desarollo)
Query Parameters
{
"message": "the format is not supported by the order"
}
shippingTrackingId: Tracking ID del envío
shippingLabelUrl: URL para descargar el PDF, ZPL ó guía
shippingCourier: Paquetería utilizada para el envío
shippingCourierCode(opcional): Código opcional a requerir según el canal de la venta (solo aplica en Liverpool)
shippingInvoiceNumber(opcional):ID de Factura para asociar la guía
Comportamiento por canal
MercadoLibre: shippingTrackingId, status(solo para el update si es creación se pone por defecto "shipped").
Wish:shippingTrackingId, shippingCourier.
WalmartEDI: shippingTrackingId, shippingCourier, shippingLabelUrl.
Vtex : shippingTrackingId,shippingCourier,shippingInvoiceNumber ,shippingLabelUrl.
Elektra: shippingTrackingId, shippingCourier, shippingLabelUrl.
Amazon: shippingTrackingId, shippingCourier.
Shopify: shippingTrackingId, shippingCourier, shippingLabelUrl.
Liverpool: shippingTrackingId, shippingCourier, shippingCourierCode, shippingLabelUrl.
WooCommerce: N/A
Claroshop: N/A
Linio: N/A
TiendaNube : N/A
Este método solamente sirve si tienes activo el módulo de Productos Digitales. Al hacer uso de este endpoint, se notificará al usuario sobre la compra de su producto digital, entregandole una liga para que pueda verificar la data de redeem
Path Parameters
Body de la llamada:
{"orderId": "4592185",//ID DE VENTA INTERNO DE VENTIAPP"dateRedeem": "18/02/2021","redeems": [ {"productName":"OFFICE","brand":"OFFICE","key":"KEY012345678",//OPCIONAL"description":"MICROSOFT 365 EMPRESA BÁSICO" }, {"productName":"Avast Free Antivirus 2021","brand":"Avast","urlRedeem":"https://www.avast.com/redeem?id=123456",//OPCIONAL"description":"Detecte virus, ransomware y otras amenazas en tiempo real." } ],"messages":[ //OPCIONAL {"text":"Hola {{NOMBRE}} {{APELLIDO}}, gracias por comprar en {{NOMBRE_TIENDA}}" }, {"text":"Para hacer Redeem de tu licencia de {{NOMBRE_PRODUCTO}} deberás ingresar aquí {{LINK_REDEEM}}" }, {"text":"Te recordamos que puedes verificar nuestros tutoriales en los adjuntos dentro del portal de redeem" } ],"attachments":[ //OPCIONAL {"url":"https://ventiapp.com/help/redeem.pdf","text":"Manual de redeem para producto digital" }, {"url":"https://ventiapp.com/help/redeem2.pdf","text":"Manual de redeem 2 para producto digital" }, ] }
Información sustituible:
El nuevo campo de messages soporta información sustituible, la cual se generará a partir de la información de la orden. Los campos son los siguientes:
{{NOMBRE}} -> Nombre del comprador
{{APELLIDO}} -> Apellido del comprador
{{NOMBRE_PRODUCTO}} -> Nombre del item que se compro en la orden
{{NOMBRE_TIENDA}} -> Nombre de la tienda oficial, ó nombre del usuario del canal de venta
{{LINK_REDEEM}} -> Aquí aparecerá el link hacia el portal de redeem de Ventiapp
En el apartado de Webhook se definen notas importantes de las cuales es recomendado que se tengan en cuenta, sobre todo con compras de Mercado Libre y Linio. Ver aquí
Fechas
Todos los campos de fechas que se retornan por API están en Zona Horaria Universal (UTC), la cual deberás calcular si deseas tener en tiempo local de tu país.
Estados posibles de órdenes
A partir del 21/10/2020 las ordenes consultadas por API tendrán la siguiente unificación de los estados originales del canal a los siguientes.
Estados posibles de logística
Existen varios tipos distintos de logística de acuerdo al tipo de órden que se generer desde la plataforma web ó marketplace. A continuación una lista de los estados más utilizados, es posible que existan adicionales en casos especiales. Este campo es shippingCourier
Con esta función podrás ocultar permanentemente la información de los compradores. La PII (Información Personal) será reemplazada dentro de los datos de Ventiapp.
El sistema recibe un arreglo de enteros como en el ejemplo
El máximo de órdenes en simultáneo para ofuscar es 50 órdenes
Request Body
{"message": "personal information redacted","orders":["12345","12351","45412","434912315233","20000000142461235"]"}
Fecha mínima de la cual se requieren las órdenes. formato MM/DD/YYYY ej: 06/30/2019
to
string
Fecha máxima de la cual se requieren las órdenes. formato MM/DD/YYYY ej: 06/30/2019
offset
number
Cantidad de órdenes salteadas, ejemplo offset = 50 nos traerá de la órden 51 a la 100
paging
number
Cantidad de items por página, máximo 50 items
sort
string
Tipo de ordenamiento van a tener las ordenes, mas detalle a continuación
isGrouped
boolean
(BETA) Agrupa las órdenes por número de carrito
searchDateBy
string
Tipo de fecha para el valor del parámetro "date". sus posibles valores son "added", "created", "modified"
Authorization
string
Bearer +token
orderid
string
ID Externo de la órden ó ID de carrito en caso de aplicar (ej: ID de MercadoLibre, se encuentra en número de órden y tiene un valor como el siguiente 111444123)
orderId
string
externalId
string
ID externo de la venta (del marketplace o plataforma de ecommerce)
type
string
Tipo de guía que se desea imprimir
orderId
integer
ID de Ventiapp
orderId*
string
ID de la venta (Parámetro obligatorio)
orderId
string
Internal Order ID from Ventiapp or External Order Id
orderId
string
Internal Order ID from Ventiapp or External Order Id
string
externalID*
String
ID externo de la venta
erpID*
String
ID que se desea asignar a la venta
canal*
String
Canal de venta perteneciente a la venta (Mercado Libre, Amazon, etc)
ventaId*
int
Id interno de la venta
erpId*
String
Id que se desea colocar en la venta
Estado
Descripción
confirmed
Confirmada, sin pagar
pending
Orden pendiente, en estado de espera
paid
Pagada
cancelled
Cancelada
returned
Retornada
refused
Rechazada
partial_returned
Devolución Parcial
Estado
Descripción
drop_off
Estado de Dropshipping, cuando tu negocio está encargado del envío
xd_drop_off
Estado de Dropshipping, cuando tu negocio está encarado del envío pero este será auna agencia
fulfillment
Estado de envío de Fulfillment, estará encargado el marketplace
custom
Estado de envío customizado, generalmente es cuando el usuario define sus tipos de envío
not_specified
Estado de envío sin especificar, en este caso hay que ponerse de acuerdo con el comprador
orders*
Array
ID Interno ú Externo de la Venta
orderId
String
Id original del canal de venta, es requerido en caso de que el parámetro ventiOrderId venga vacío
ventiOrderId
int
Id de venta de Ventiapp, es requerido en caso de que el parámetro orderId venga vacío
