Ventas

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

Referencias: Archivo de estados de ventas.

58KB

Integraciones - Status Ventas.xlsx

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"

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 protected]",//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 protected]", //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 protected]",
        "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": "[email protected]",
                "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": "[email protected]",
        "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 protected]",
			"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 protected]",
			"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 - Claroshop - Amazon (en desarrollo) - Walmart (en desarollo)

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": "1 | 2 | 3",
            "guideTrackingUrl": null,
            "courierName": "fedex"
        }
    ],
    "sellerInfo": null,
    "sellerId": null,
    "shipmentType": null,
    "shippingStatus": null,
    "shippingCourier": null,
    "shippingId": null,
    "shippingType": null,
    "ventiShipping": false,
    "ventiCourierId": null,
    "shippingTrackingId": "1 | 2 | 3",
    "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"
}

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

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)

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
}