Publicaciones

En esta sección podrás informarte de como realizar una publicación en un canal externo, Marketplace o tienda de e-Commerce

Flujo de Datos

Generar un publicación puede ser un proceso complejo, cada canal tiene sus especificaciones y requerimientos. Ventiapp se encargará de facilitar la tarea de mapeo de datos hacia los canales, pero estos pueden estar en constante actualización. Será trabajo del desarrollador tener una correcta gestión del mapeo de categorias y atributos para las publicaciones de cada canal.

Es importante que el flujo de datos para la integración sea correcto, a continuación el diagrama correcto

Actualmente esta funcionalidad está disponible solamente para Mercado Libre

Get Listing Options

GET https://ventiapi.azurewebsites.net/api/listing/getOptions

Este metodo brindará las opciones disponibles para realizar una publicación, sin estas opciones no podrás continuar en el paso de Listing Create

Path Parameters

Name	Type	Description
Seller	string	Seller ID (optional)
ParentSku	string	Parent SKU
Channel	string	Channel name (i.e: meli)

Headers

Name	Type	Description
Authorization	string	Bearer + token
Content-Type	string	application/json

200 Respuesta del servidor, en este caso son opciones de publicación para Mercado Libre

{
    "accountName": "TESTBXXXXX",
    "listingTypePublish": [
        {
            "id": 1,
            "name": "Premium"
        },
        {
            "id": 3,
            "name": "Clásica"
        }
    ],
    "listingTypeShipping": [
        {
            "name": "Mercado Envíos",
            "mode": "me2"
        },
        {
            "name": "Personalizado",
            "mode": "custom",
            "options": [
                {
                    "id": 1,
                    "name": "Envio Personalizado 1",
                    "cost": 33.5400
                },
                {
                    "id": 3,
                    "name": "Envio Personalizado 2",
                    "cost": 0.0000
                },
                {
                    "id": 7,
                    "name": "Envio Personalizado 3",
                    "cost": 93.4500
                },
                {
                    "id": 37,
                    "name": "Envio Personalizado 4",
                    "cost": 89.0000
                },
                {
                    "id": 40,
                    "name": "Envio Personalizado 5",
                    "cost": 23.0000
                },
                {
                    "id": 65,
                    "name": "Envio Personalizado 5",
                    "cost": 455.0000
                },
                {
                    "id": 69,
                    "name": "Envio Personalizado 6",
                    "cost": 99.9900
                }
            ]
        },
        {
            "name": "Mercado Envíos 1",
            "mode": "me1"
        }
    ],
    "listingStores": []
}

Listing Create

POST https://ventiapi.azurewebsites.net/api/listing/create

Este método es utilizado para crear una nueva publicación, es necesario que tenga todas las opciones requeridas por el canal.

A pesar de que los parámetros id y parentSku son opcionales, al menos uno de los dos debe ser enviado para poder publicar el producto.

Canales disponibles

Mercado Libre - "meli"

Shopify - "shopify"

Magento - "magento"

Path Parameters

Name	Type	Description
channel*	string	Canal en donde se desea crear la publicación
id	int	Id interno del producto dentro de Ventiapp
parentSku	string	Sku padre del producto

200

//EJEMPLO LISTING/CREATE (Mercado Libre)

{
  "sellerId": "234245",
  "listingTypeId": 1,
  "listingModeShipping": "me2",
  "listingCustomShippingId": null,
  "officialStoreId": null,
  "freeShipping": false,
  "localPickup": false,
  "fulfillment": false,
  "mshops": false,
  "sizeChartId": 32321
}

Get Attributes

GET https://ventiapi.azurewebsites.net/api/listing/GetRequiredAttributes

Los atributos devueltos pueden ser de dos tipos:

Con valores predeterminados. Este tipo de atributos cuenta con un array de valores (values) que determinan los valores válidos para este atributo (véase response body). El campo freeValues viene como false.

Con valor libre. Este tipo de atributo acepta cualquier valor tipo string. El campo freeValues viene como true.

Descripción de los campos de los atributos

id. Identificador del atributo. Sirve para identificar un atributo al usar el endpoint UpdateAttributes.

name. Campo informativo que representa el nombre del atributo.

values. Lista de valores permitidos para el atributo. En caso de que el campo freeValues sea true y haya una lista de valores, la lista es sólo una lista de sugerencias.

freeValues. Este campo determina si el atributo puede recibir cualquier valor o necesita ser tomado de una lista de atributos determinada. Si el valor es true, se puede colocar cualquier valor cuando se actualiza un atributo determinado, en caso de ser false, el valor debe ser tomado de la lista de valores perteneciente al atributo.

Canales disponibles

Mercado Libre - "meli"

Magento - "magento"

Path Parameters

Name	Type	Description
categoryId*	String	Id de la categoría
channel	String	Canales disponibles

200: OK Devuelve correctamente los atributos

// Ejemplo Mercado Libre
[
    {
        "id": "BRAND",
        "name": "Marca",
        "values": null,
        "isMandatory": false,
        "freeValues": true
    },
    {
        "id": "MODEL",
        "name": "Modelo",
        "values": null,
        "isMandatory": false,
        "freeValues": true
    },
    {
        "id": "COLOR",
        "name": "Color",
        "values": [
            {
                "id": "52019",
                "name": "Verde oscuro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283160",
                "name": "Turquesa",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52022",
                "name": "Agua",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283162",
                "name": "Índigo",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52036",
                "name": "Lavanda",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283163",
                "name": "Rosa chicle",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "51998",
                "name": "Bordó",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52003",
                "name": "Nude",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52055",
                "name": "Blanco",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283161",
                "name": "Azul marino",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52008",
                "name": "Crema",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52045",
                "name": "Rosa pálido",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283153",
                "name": "Suela",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283150",
                "name": "Naranja claro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52028",
                "name": "Azul",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52043",
                "name": "Rosa claro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283148",
                "name": "Coral claro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283149",
                "name": "Coral",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52021",
                "name": "Celeste",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52031",
                "name": "Azul acero",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283156",
                "name": "Caqui",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52001",
                "name": "Beige",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "51993",
                "name": "Rojo",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "51996",
                "name": "Terracota",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283165",
                "name": "Gris",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52035",
                "name": "Violeta",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283154",
                "name": "Marrón claro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52049",
                "name": "Negro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283155",
                "name": "Marrón oscuro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52053",
                "name": "Plateado",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52047",
                "name": "Violeta oscuro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "51994",
                "name": "Rosa",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52007",
                "name": "Amarillo",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283157",
                "name": "Verde lima",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52012",
                "name": "Dorado oscuro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52015",
                "name": "Verde claro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283151",
                "name": "Naranja oscuro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52024",
                "name": "Azul petróleo",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52051",
                "name": "Gris oscuro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283152",
                "name": "Chocolate",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52014",
                "name": "Verde",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283164",
                "name": "Dorado",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52000",
                "name": "Naranja",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52033",
                "name": "Azul oscuro",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52010",
                "name": "Ocre",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "283158",
                "name": "Verde musgo",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52005",
                "name": "Marrón",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52038",
                "name": "Lila",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52042",
                "name": "Fucsia",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "338779",
                "name": "Cian",
                "valueid": null,
                "metadata": null
            },
            {
                "id": "52029",
                "name": "Azul claro",
                "valueid": null,
                "metadata": null
            }
        ],
        "isMandatory": false,
        "freeValues" : true
    },
     {
        "id": "IS_FLAMMABLE",
        "name": "Es inflamable",
        "values": [
            {
                "id": "242084",
                "name": "No",
                "valueid": null,
                "metadata": {
                    "value": false,
                    "rgb": null
                }
            },
            {
                "id": "242085",
                "name": "Sí",
                "valueid": null,
                "metadata": {
                    "value": true,
                    "rgb": null
                }
            }
        ],
        "isMandatory": false,
        "freeValues": false
    }

]

400: Bad Request Canal no disponible

{
    "message": "channel {channel} not found."
}

500: Internal Server Error Error del servidor

{
    "message": "Error: No response was obtained from the server."
}

Update Attributes

POST https://ventiapi.azurewebsites.net/api/listing/UpdateAttributes

Actualiza los atributos de las publicaciones en Mercado Libre.

Descripciones de los campos contenidos dentro de la lista "values":

id. Identificador del atributo obtenido en el endpoint GetRequiredAttributes.

value. Valor del atributo. En caso de que sea un atributo con valores predeterminados (Ver endpoint GetRequiredAttributes) Se necesita llenar con el campo id de algún elemento seleccionado de la lista, en caso de ser un atributo con valor libre se puede llenar con cualquier valor

Canales disponibles

Mercado Libre - "meli"

Magento - "magento"

Request Body

Name	Type	Description
items*	string array	Lista de identificadores de mercado libre (no es requerido en Magento)
values*	object array	Lista de atributos a mandar. Ejemplo anexo más adelante
channel	String	Si no hay valor en channel se tomará como Mercado Libre

200: OK OK

[
    {
        "id": "MLM1306733882",
        "status": "success",
        "msg": null
    }
]

Ejemplo request body Update Attributes

// Ejemplo Mercado Libre
{
  "items": [
    "MLM1306733866"
  ],
  "values": [
    {
      "id": "BRAND",
      "value": "TESTING"
    },
    {
        "id": "COLOR",
        "value" : "283160"
    }
  
  ]
}

Guía de tallas

Esta sección engloba los procesos relacionados a las guías de tallas

Obtener las opciones disponibles para crear una guía de talla

GET https://ventiapi.azurewebsites.net/api/Listing/GetSizeChartOptions

Este recurso obtiene las variables disponibles para crear una guía de talla (Creación de guía de talla pendiente)

200: OK Lista de opciones disponibles

[
    {
        "id": "BR_EQUIVALENCE",
        "name": "BR",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": ""
        }
    },
    {
        "id": "CHEST_CIRCUMFERENCE",
        "name": "Contorno del pecho",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "CHILD_HEIGHT",
        "name": "Altura del nio",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "EUR_EQUIVALENCE",
        "name": "EUR",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": ""
        }
    },
    {
        "id": "FOOT_LENGTH",
        "name": "Largo del pie",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "FOOT_WIDTH",
        "name": "Ancho del pie",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "HIP_CIRCUMFERENCE",
        "name": "Contorno de la cadera",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "INSEAM_LENGTH",
        "name": "Largo de la entrepierna",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "NECK_CIRCUMFERENCE",
        "name": "Contorno del cuello",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "SLEEVE_LENGTH",
        "name": "Largo de manga",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "TOTAL_LENGTH",
        "name": "Largo total",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "UK_EQUIVALENCE",
        "name": "UK",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": ""
        }
    },
    {
        "id": "US_EQUIVALENCE",
        "name": "US",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": ""
        }
    },
    {
        "id": "WAIST_CIRCUMFERENCE",
        "name": "Contorno de la cintura",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "cm"
        }
    },
    {
        "id": "WEIGHT",
        "name": "Peso",
        "type": {
            "id": "NUMBER_UNIT",
            "default_unit": "kg"
        }
    }
]

Obtener guías de tallas creadas

GET https://ventiapi.azurewebsites.net/api/Listing/GetAllSizeCharts

Obtiene todas las guías de talla creadas por el usuario de la cuenta de Mercado Libre

200: OK

[
    {
        "integrationSellerId": "346634509",
        "sizeCharts": [
            {
                "id": 2022143,
                "name": "guia test",
                "columns": [
                    {
                        "id": "CHEST_CIRCUMFERENCE",
                        "name": "Contorno del pecho",
                        "type": {
                            "id": "NUMBER_UNIT",
                            "default_unit": "cm"
                        }
                    }
                ],
                "sizes": [
                    {
                        "name": "30",
                        "measurements": [
                            {
                                "id": "CHEST_CIRCUMFERENCE",
                                "value": 50.0
                            }
                        ]
                    },
                    {
                        "name": "40",
                        "measurements": [
                            {
                                "id": "CHEST_CIRCUMFERENCE",
                                "value": 50.0
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

Obtener items dentro de una guía de talla

GET https://ventiapi.azurewebsites.net/api/Listing/GetSizeChartItems

Este recurso obtiene las publicaciones utilizadas para una guía de talla específica

Path Parameters

Name	Type	Description
chartId*	int	id de la guía de talla (Obtenida por el recurso GetAllSizeCharts)

200: OK Productos con la guía de talla especificada

{
    "items": [
        "MLM1306733882"
    ]
}

Asignar guía de talla a lista de publicaciones

POST http://ventiapi.azurewebsites.net/api/Listing/ApplySizeChart

Este recurso asigna una guía de talla específica a una lista de publicaciones

// EJEMPLO BODY DE APPLYSIZECHART

{
  "chartId": 2022143,
  "ids": [
    "MLM1306733882",
    "MLM1306743882"
  ]
}

Cambio de status de productos

Esta sección engloba los procesos de actualización de status de las publicaciones

Activar / Desactivar publicación

GET https://ventiapi.azurewebsites.net/api/listing/changestatuspub

Este método cambia el status de las publicaciones asignadas a determinados productos. Esta función está disponible por ahora sólo para Mercado Libre

Path Parameters

Name	Type	Description
channel*	String	Canal al que va aplicada esta actualización (por ahora sólo disponible el valor "meli")
externalId*	String	Id externo de la publicación
active*	bool	Parámetro que determina si la publicación se activará o no
id	int	Id interno de Ventiapp (Opcional)
parentSku		Sku padre del producto (Opcional)

200: OK Todo salió bien

{
    // Response
}

400: Bad Request La publicación no existe o no es modificable

{
    // Response
}

Buscar productos con publicaciones

GET https://ventiapi.azurewebsites.net/api/listing/Search

Este método busca algún producto que cuente con publicaciones y sus variaciones.

Canales permitidos:

Amazon "amazon"

Claroshop "claroshop"

Elektra "elektra"

Linio "linio"

Mercado Libre "meli"

Mercado Shops "mshops"

Prestashop "prestashop"

VentiCommerce "venticommerce"

Vtex "vtex"

Walmart "walmart"

Wish "wish"

WooCommerce "woocommerce"

Liverpool "liverpool"

WalmartEDI (México) "walmartEDI"

Amazon (Estados Unidos) "amazonUS"

Walmart (Estados Unidos) "walmartUS"

TiendaNube "tiendanube"

Magento "magento"

Bestbuy (Canadá) "bestbuyca"

Cyberpuerta "cyberpuerta"

Path Parameters

Name	Type	Description
paging	int	Paginado de productos
offset	int	Punto de búsqueda inicial
title	string	Título del producto
parentSku	string	Sku del producto

200: OK

{
    "products": [
        {
            "listing": [
                {
                    "listingVariations": [
                        {
                            "productVariationID": 1888494,
                            "externalID": "174257571909",
                            "sku": "lvl1hlmt1-2-edit",
                            "name": "Color",
                            "value": "morado",
                            "name2": null,
                            "value2": null,
                            "name3": null,
                            "value3": null,
                            "stock": 5,
                            "price": 700.0000
                        },
                        {
                            "productVariationID": 1888493,
                            "externalID": "174257571910",
                            "sku": "lvl1hlmt1-1",
                            "name": "Color",
                            "value": "Rojo",
                            "name2": null,
                            "value2": null,
                            "name3": null,
                            "value3": null,
                            "stock": 5,
                            "price": 700.0000
                        }
                    ],
                    "channel": "meli",
                    "title": "Helmet Level 1",
                    "url": "http://articulo.mercadolibre.com.mx/MLM-1306733882-helmet-level-1-_JM",
                    "price": 700.0000,
                    "offerPrice": 0.0,
                    "stock": 10,
                    "listingType": "gold_pro",
                    "shippingType": "me2",
                    "status": "active",
                    "freeShipping": "True",
                    "externalCategoryId": "MLM178308",
                    "externalId": "MLM1306733882",
                    "dateAdded": "2021-09-07T12:25:15.55"
                },
                {
                    "listingVariations": [
                        {
                            "productVariationID": 1888494,
                            "externalID": "39841716142162",
                            "sku": "lvl1hlmt1-2-edit",
                            "name": "Color",
                            "value": "morado",
                            "name2": null,
                            "value2": null,
                            "name3": null,
                            "value3": null,
                            "stock": 40,
                            "price": 100.0000
                        },
                        {
                            "productVariationID": 1888493,
                            "externalID": "39841716174930",
                            "sku": "lvl1hlmt1-1",
                            "name": "Color",
                            "value": "Rojo",
                            "name2": null,
                            "value2": null,
                            "name3": null,
                            "value3": null,
                            "stock": 1,
                            "price": 199.0000
                        }
                    ],
                    "channel": "shopify",
                    "title": "Helmet Level 1",
                    "url": "https://kubostore.myshopify.com/products/helmet-level-1",
                    "price": 199.0000,
                    "offerPrice": 0.0,
                    "stock": 41,
                    "listingType": "15540663287890",
                    "shippingType": "15408852041810",
                    "status": "active",
                    "freeShipping": null,
                    "externalCategoryId": "",
                    "externalId": "1563463745618",
                    "dateAdded": "2021-08-16T23:28:37.51"
                }
            ],
            "sku": "lvl1hlmt1",
            "price": 199.0000,
            "title": "Helmet Level 1 ",
            "ean": null,
            "upc": null,
            "longDescription": "<p><br></p>",
            "shortDescription": "",
            "baseStock": 1,
            "brand": null,
            "model": "",
            "weight": 100.0,
            "height": 10.0,
            "width": 10.0,
            "depth": 10.0,
            "packageWeight": 100.0,
            "packageHeight": 10.0,
            "packageWidth": 10.0,
            "packageDepth": 10.0,
            "used": false,
            "warranty": "",
            "videoUrl": ""
        },
        {
            "listing": [
                {
                    "listingVariations": [],
                    "channel": "meli",
                    "title": "Helmet Level 2",
                    "url": "http://articulo.mercadolibre.com.mx/MLM-1367696886-helmet-level-2-_JM",
                    "price": 199.0000,
                    "offerPrice": 0.0,
                    "stock": 6,
                    "listingType": "gold_pro",
                    "shippingType": "me2",
                    "status": "active",
                    "freeShipping": "True",
                    "externalCategoryId": "MLM178308",
                    "externalId": "MLM1367696886",
                    "dateAdded": "2022-01-20T08:46:55.733"
                },
                {
                    "listingVariations": [],
                    "channel": "shopify",
                    "title": "Helmet Level 2",
                    "url": "https://kubostore.myshopify.com/products/helmet-level-2",
                    "price": 199.0000,
                    "offerPrice": 199.0000,
                    "stock": 6,
                    "listingType": "42027993202770",
                    "shippingType": "39931220000850",
                    "status": "active",
                    "freeShipping": null,
                    "externalCategoryId": "",
                    "externalId": "6878476828754",
                    "dateAdded": "2022-01-20T14:46:55.733"
                }
            ],
            "sku": "lvl2hlmt",
            "price": 199.0000,
            "title": "Helmet Level 2",
            "ean": null,
            "upc": null,
            "longDescription": "<p><br></p>",
            "shortDescription": "",
            "baseStock": 1,
            "brand": null,
            "model": "",
            "weight": null,
            "height": null,
            "width": null,
            "depth": null,
            "packageWeight": null,
            "packageHeight": null,
            "packageWidth": null,
            "packageDepth": null,
            "used": false,
            "warranty": "",
            "videoUrl": ""
        }
    ],
    "paging": 50,
    "offset": 1,
    "totalProducts": 2
}