ventiapp/Documentación

Ventas

Ventas

En esta sección se encuentran todas las API's de Ventiapp relacionadas a Ventas

Referencias: Archivo de estados de ventas.

Contiene los estados de cada marketplace

Get Orders

GET https://ventiapi.azurewebsites.net/api/orders/orders

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

channel

string

Canal para poder filtrar las ventas

date*

string

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"

status

string

Status global del la orden, puede ser "CREATED", "SHIPPED", "CANCELED", "RETURNED", "DELIVERED", "READY_TO_SHIP", "PROCESSING", "PARTIALLY_CANCELED"

Headers

Name

Type

Description

Authorization

string

Bearer +token

200 Ventas obtenidas

{
  "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,
       "ShipmentChargedTo": "buyer"
      },
      "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",
      "externalStatus": "CREATED",
      "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:

  • "amazon" (Amazon)
  • "claroshop" (Claroshop)
  • "elektra" (Elektra)
  • "linio" (Linio)
  • "liverpool" (Liverpool)
  • "meli" (Mercado Libre)
  • "mshops" (Mercado Shops)
  • "prestashop" (Prestashop)
  • "shopify" (Shopify)
  • "venticommerce" (VentiCommerce)
  • "vtex" (VTEX)
  • "walmart" (Walmart) //Plataforma antigua MIRAKL //DEPRECATED
  • "walmartEDI" (Walmart) // Plataforma nueva Walmart EDI
  • "wish" (Wish)
  • "woocommerce" (WooCommerce)
  • "walmartUS" (Walmart United States) //Version USA
  • "amazon_us" (Amazon United States) //Version USA
  • "tiendanube" (Tienda Nube)
  • "ventiapp" (Órdenes creadas manualmente o através de POS)
  • "coppel" (Coppel)

Find Order

GET https://ventiapi.azurewebsites.net/api/orders/findorder

Este método busca una venta en específico, o un carrito con órdenes asociadas.

Query Parameters

Name

Type

Description

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)

200 Venta obtenida

{
  "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,
      "externalStatus": "CREATED",
      "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,
        "ShipmentChargedTo": "buyer"
      },
      "paymentMethods": [
                {
                    "externalId": "5531048951",
                    "paymentMethod": "oxxo"
                }
            ],
      "accountName" : "MY_MELI_USER"
    }
  ]
}

Create Order

POST https://ventiapi.azurewebsites.net/api/orders/CreateOrder

Este método es utilizado para crear una orden en Ventiapp

200

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

Update Order

PUT https://ventiapi.azurewebsites.net/api/orders/updateorder/

Este método es utilizado para actualizar una órden en Ventiapp. Los campos son opcionales, los que no se encuentren en la llamada serán ignorados

Query Parameters

Name

Type

Description

orderId

string


200

{
	"message": "order created successfully",
	"order": {
		"orderId": 1234,
		"channel": "your_channel",
		"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",
		"items": [{
				"itemExternalId": "MLM3312341",
				"title": "Item 1",
				"price": 460.0,
				"variationId": "13818313",
				"variationName": "Red",
				"itemQuantity": 1,
				"total": 460.0,
				"sku": "ITEM-RED001",
				"erpId": null
			},
			{
				"itemExternalId": "MLM3317841",
				"title": "Item 2",
				"price": 200.0,
				"variationId": null,
				"variationName": null,
				"itemQuantity": 1,
				"total": 200.0,
				"sku": "PLAINITEM001",
				"erpId": 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"
		},
		"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"
		}
	}
}

Ejemplo de la llamada:

{
		
		"channel": "your_channel", 
		"externalId": "111444123", 
		"total": 660.0,
		"currency": "MXN",
		"tax": 0.16,
		"comments": "Send it before tuesday",
		"title": "Order Title",
		"cartId": "00000101110002",
		"externalNumber": "12314512",
		"items": [{
				"itemExternalId": "MLM3312341",
				"title": "Item 1",
				"price": 460.0,
				"itemQuantity": 1,
				"total": 460.0,
				"sku": "ITEM-RED001",
				"erpId": "ITEM-123"
			},
			{
				"itemExternalId": "MLM3317841",
				"title": "Item 2",
				"price": 200.0,
				"itemQuantity": 1,
				"total": 200.0,
				"sku": "PLAINITEM001",
				"erpId": "ITEM-456"
			}
		],
		"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"
		},
		"shipping": {
			"sellerInfo": "MYSELLERNAME",
			"sellerId": "MYSELLERID",
			"shipmentType": "Express",
			"shippingStatus": "shipped",
			"shippingCourier": "drop_off",
			"shippingId": "27586098188",
			"shippingTrackingId": "10003313132",
			"shippingCourierExternal": "Fedex Express"
		}

Print Label

GET https://ventiapi.azurewebsites.net/api/orders/printlabel/

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
  • Liverpool
  • Claroshop
  • Amazon (Sólo para Easy Ship)
  • Walmart
  • TikTok
  • Coppel

Query Parameters

Name

Type

Description

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

200 Procede a la descarga del archivo en formato .zpl o .pdf

409 Cuando el formato no es soportado por la orden. Ejemplo: El canal no genera guías, ó no genera en un formato específico

{
    "message": "the format is not supported by the order"
}

GetShippingByOrder

GET https://ventiapi.azurewebsites.net/api/orders/GetShippingByOrder?orderid=10710930

Este método devuelve el detalle del envío de una venta.

Query Parameters

Name

Type

Description

orderId*

string

ID de la venta (Parámetro obligatorio)

printLabel

bool

Indica si se desea realizar la obtención de la guía antes de obtener su información (Tomar en cuenta que este proceso inicia el tiempo de manejo del pedido)

200: OK

{
    "externalId": "CPTEST-07",
    "items": [ // Las guías de una venta
        {
            "externalId": "CPTEST-07",
            "guideUrl": "http://ventiapp.blob.core.windows.net/files/FE448DF5/GuiaShippingCyberPuerta_13_4_2022_18_54_7_235.pdf.pdf?sp=r&st=2021-03-04T17:03:04Z&se=2072-03-05T01:03:04Z&sv=2020-08-04&sr=c&sig=3fTU042IxoJaBGqKOYi4bnjLAQ1Afen3E2FXw8FGL%2FU%3D",
            "guideReference": "10003313132",
            "guideTrackingUrl": null,
            "courierName": "fedex"
        }
    ],
    "sellerInfo": null,
    "sellerId": null,
    "shipmentType": null,
    "shippingStatus": null,
    "shippingCourier": null,
    "shippingId": null,
    "shippingType": null,
    "ventiShipping": false,
    "ventiCourierId": null,
    "shippingTrackingId": "10003313132",
    "shippingCourierExternal": "fedex",
    "shippingCost": null,
    "fulfillment": "dropshipping",
    "shippingReceptor": "CyberPuerta",
    "country": "México",
    "shippingDiscount": null,
    "shippingCostPromo": null,
    "clientCouponAmount": null,
    "shippingRealCost": null
}

Update Shipping Label

POST https://ventiapi.azurewebsites.net/api/orders/updateshippinglabel/?orderId=XXXX

Este método es utilizado para actualizar la información de envío y guía de shipping de una venta.

Path Parameters

Name

Type

Description

orderId

string

Internal Order ID from Ventiapp or External Order Id

200

{
	"message": "shipping updated successfully",
	"orderId": "123456"
}

Body de la llamada:

{
		"shippingTrackingId": "78713341882", 
		"shippingLabelUrl": "https://myserver.com/78713341882.pdf", 
		"shippingCourier": "DHL",
		"shippingCourierCode": "XXX",
		"shippingInvoiceNumber": "INV0001",
		"shippingTrackingUrl": "https://myserver.com/tracking/234353433634"
}

Campos

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

shippingTrackingUrl: URL del seguimiento de 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

Update Shipping Status

POST https://ventiapi.azurewebsites.net/api/orders/updateshippingstatus/?orderId=XXXX

Este método es utilizado para actualizar el estado del envío de una orden.

Path Parameters

Name

Type

Description

orderId

string

Internal Order ID from Ventiapp or External Order Id

200

{
	"message": "shipping status updated successfully",
	"orderId": "1231256"
}

Body de la llamada:

{
		"shippingStatus": "shipped"
}

Add Digital Redeems

POST https://ventiapi.azurewebsites.net/api/orders/adddigitalredeems

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

Name

Type

Description


string


200

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

Update external ID

PUT https://ventiapi.azurewebsites.net/api/orders/UpdateExternalErpId

Este método es utilizado para crear o actualizar el ErpId en Ventiapp, los campos son obligatorios.

Path Parameters

Name

Type

Description

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)

orderId

int

ID interno de Venti, si se manda, no es necesario mandar el parámetro externalID ni canal

200: OK Actualización correcta de la venta

[
    {
        "ventaextId": "20850823230486",
        "erpId": "Test",
        "messageR": "IdERP Created successfully"
    }
]

400: Bad Request No se mandó el valor a asignar

{
    "message": "Data erpID cannot be null."
}

500: Internal Server Error Error interno

{
    "message": "There was an error, contact technical support."
}

Las opciones válidas para el parámetro canal son:

  • "meli" (Mercado Libre)
  • "amazon" (Amazon)
  • "amazon_us" (Amazon United States) // Version USA
  • "bestbuyca" (Best Buy CA) // Version Canada
  • "claroshop" (Claroshop)
  • "cyberpuerta" (Cyberpuerta)
  • "doto" (Doto)
  • "elektra" (Elektra)
  • "linio" (Linio)
  • "liverpool" (Liverpool)
  • "magento" (Magento)
  • "market" (Market)
  • "mshops" (Mercado Shops)
  • "prestashop" (Prestashop)
  • "shiphero" (ShipHero)
  • "shopify" (Shopify)
  • "tiendanube" (Tienda Nube)
  • "ventiapp" (Ventiapp)
  • "venticommerce" (VentiCommerce)
  • "vtex" (VTEX)
  • "walmart" (Walmart)
  • "walmartus" (Walmart United States) // Version USA
  • "walmartedi" (Walmart) // Plataforma Walmart EDI
  • "wish" (Wish)
  • "woocommerce" (WooCommerce)

Update ERP ID

POST https://ventiapi.azurewebsites.net/api/orders/UpdateErpId

Este método es utilizado para actualizar el ErpId en Ventiapp, los campos son obligatorios.

Path Parameters

Name

Type

Description

ventaId*

int

Id interno de la venta

erpId*

String

Id que se desea colocar en la venta

200: OK OK

[
    {
        "ventaextId": "2000003508461232104",
        "erpId": "test",
        "messageR": "IdERP Updated successful"
    }
]

400: Bad Request erpId es nulo o vacío

{
    "message": "Data erpID cannot be null."
}

Notas importantes

Webhooks

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.

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

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



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

Ofusca datos personales de los compradores

POST https://ventiapi.azurewebsites.net/api/orders/redact

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

Name

Type

Description

orders*

Array

ID Interno ú Externo de la Venta

200: OK Ordenes Ofuscadas

{
	"message": "personal information redacted",
	"orders":["12345","12351","45412","434912315233","20000000142461235"]"
}

Body de la llamada:

{
    "orders":["12345","12351","45412","434912315233","20000000142461235"]
}

Cancela ó notifica requerimiento de Cancelación

POST https://ventiapi.azurewebsites.net/api/orders/CancelOrder

En desarrollo

Obtiene la devolución de una venta en específico

GET https://ventiapi.azurewebsites.net/api/orders/GetReturn

Esta operación devuelve la devolución de una venta, por ahora disponible únicamente para Mercado Libre

Path Parameters

Name

Type

Description

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

200: OK Respuesta exitosa

{
    "estimatedDate": "2023-01-05T06:00:00+00:00",
    "shippingTrackingId": "MEL00003091766319",
    "courierName": "MEL Distribution",
    "itemCost": 440.1000
}

404: Not Found Venta no encontrada

{
    // Response
}

400: Bad Request Ambos parámetros están vacíos, la venta no tiene un reclamo o no es del tipo devolución

{
    // Response
}

Obtener actividad de orden

GET``https://ventiapi.azurewebsites.net/api/orders/GetOrderActivity

Devuelve las actualizaciones de una orden específica

Headers

Name

Value

Content-Type

application/json

Authorization

Bearer <token>

Parameters

Name

Type

Description

orderID

int

ID interno de la venta de Ventiapp

Response

200

[
    {
        "monthNumber": 10,
        "dayNumber": 3,
        "monthName": "Octubre",
        "logs": [
            {
                "logType": "Detailed",
                "date2": {},
                "date": "03/10/2025 2:21:07",
                "title": "Facturación sin éxito (Mostrador/Global)",
                "empresaId": 3023,
                "ventaId": 45677165,
                "metadata": "[{\"title\":\"Error 811\",\"value\":\"El campo claveProdServ dentro de CFDi.Partidas.* debe ser de 8 caracteres.\"},{\"title\":\"8b21321a-d712-4733-8867-17e8fe4d76c0\",\"value\":\"Clave:60141000 Unidad:H87\"},{\"title\":\"b67f20eb-236e-474c-b529-494fc89aa949\",\"value\":\"Clave:60141000 Unidad:H87\"},{\"title\":\"45677165\",\"value\":\"Clave:24111500 Unidad:PR\"},{\"title\":\"45348495\",\"value\":\"Clave:1013170 Unidad:H87\"}]",
                "label": "Ver más",
                "grupoId": "",
                "user": "Automático Global",
                "time": "2:21 AM",
                "timeView": "2025-10-03T02:21:07.0000000-06:00",
                "index": 0,
                "detail": [
                    {
                        "title": "Error 811",
                        "value": "El campo claveProdServ dentro de CFDi.Partidas.* debe ser de 8 caracteres."
                    },
                    {
                        "title": "8b21321a-d712-4733-8867-17e8fe4d76c0",
                        "value": "Clave:60141000 Unidad:H87"
                    },
                    {
                        "title": "b67f20eb-236e-474c-b529-494fc89aa949",
                        "value": "Clave:60141000 Unidad:H87"
                    },
                    {
                        "title": "45677165",
                        "value": "Clave:24111500 Unidad:PR"
                    },
                    {
                        "title": "45348495",
                        "value": "Clave:1013170 Unidad:H87"
                    }
                ]
            }
        ],
        "day": "2025-10-03T02:21:07-06:00"
    },
    {
        "monthNumber": 9,
        "dayNumber": 30,
        "monthName": "Septiembre",
        "logs": [
            {
                "logType": "Detailed",
                "date2": {},
                "date": "30/09/2025 2:07:50",
                "title": "Facturación sin éxito (Mostrador/Global)",
                "empresaId": 3023,
                "ventaId": 45677165,
                "metadata": "[{\"title\":\"Error 811\",\"value\":\"El campo claveProdServ dentro de CFDi.Partidas.* debe ser de 8 caracteres.\"},{\"title\":\"45962075\",\"value\":\"Clave:60141000 Unidad:H87\"},{\"title\":\"45677165\",\"value\":\"Clave:24111500 Unidad:PR\"},{\"title\":\"45348495\",\"value\":\"Clave:1013170 Unidad:H87\"}]",
                "label": "Ver más",
                "grupoId": "",
                "user": "Automático Global",
                "time": "2:07 AM",
                "timeView": "2025-09-30T02:07:50.0000000-06:00",
                "index": 1,
                "detail": [
                    {
                        "title": "Error 811",
                        "value": "El campo claveProdServ dentro de CFDi.Partidas.* debe ser de 8 caracteres."
                    },
                    {
                        "title": "45962075",
                        "value": "Clave:60141000 Unidad:H87"
                    },
                    {
                        "title": "45677165",
                        "value": "Clave:24111500 Unidad:PR"
                    },
                    {
                        "title": "45348495",
                        "value": "Clave:1013170 Unidad:H87"
                    }
                ]
            }
        ],
        "day": "2025-09-30T02:07:50-06:00"
    },
    {
        "monthNumber": 9,
        "dayNumber": 24,
        "monthName": "Septiembre",
        "logs": [
            {
                "logType": "Detailed",
                "date2": {},
                "date": "24/09/2025 11:15:16",
                "title": "Facturación sin éxito (Mostrador/Global)",
                "empresaId": 3023,
                "ventaId": 45677165,
                "metadata": "[{\"title\":\"Error 811\",\"value\":\"El campo formaDePago dentro de CFDi.DatosDePago es requerido cuando metodoDePago dentro de CFDi.DatosDePago esta presente.\"},{\"title\":\"45677165\",\"value\":\"Clave:24111500 Unidad:PR\"}]",
                "label": "Ver más",
                "grupoId": "",
                "user": "",
                "time": "11:15 AM",
                "timeView": "2025-09-24T11:15:16.0000000-06:00",
                "index": 2,
                "detail": [
                    {
                        "title": "Error 811",
                        "value": "El campo formaDePago dentro de CFDi.DatosDePago es requerido cuando metodoDePago dentro de CFDi.DatosDePago esta presente."
                    },
                    {
                        "title": "45677165",
                        "value": "Clave:24111500 Unidad:PR"
                    }
                ]
            }
        ],
        "day": "2025-09-24T11:15:16-06:00"
    },
    {
        "monthNumber": 9,
        "dayNumber": 17,
        "monthName": "Septiembre",
        "logs": [
            {
                "logType": "Detailed",
                "date2": {},
                "date": "17/09/2025 12:46:24",
                "title": "Actualización de Stock",
                "empresaId": 3023,
                "ventaId": 45677165,
                "metadata": "[{\"title\":\"Venti POS(Origen)\",\"value\":\"Se actualizó stock 0 unidades\"},{\"title\":\"Sin Autosync\",\"value\":\"Mercado Libre, Mercado Shops, Tienda Nube\"}]",
                "label": "Autosync SKU: CN5164-011-NEGRO",
                "grupoId": null,
                "time": "12:46 PM",
                "timeView": "2025-09-17T12:46:24.0000000-06:00",
                "index": 3,
                "detail": [
                    {
                        "title": "Venti POS(Origen)",
                        "value": "Se actualizó stock 0 unidades"
                    },
                    {
                        "title": "Sin Autosync",
                        "value": "Mercado Libre, Mercado Shops, Tienda Nube"
                    }
                ]
            },
            {
                "logType": "Normal",
                "date2": {},
                "date": "17/09/2025 12:46:21",
                "title": "Punto de Venta",
                "subtitle": "Se creo orden a través del punto de venta.",
                "empresaId": 3023,
                "ventaId": 45677165,
                "grupoId": "",
                "user": "",
                "time": "12:46 PM",
                "timeView": "2025-09-17T12:46:21.0000000-06:00",
                "index": 4
            }
        ],
        "day": "2025-09-17T12:46:24-06:00"
    }
]

400

{
  "error": "Invalid request"
}

¿Te fue útil este artículo?

Ventas