Conoce cómo están los vendedores frente a la carga de atributos

En Mercado Libre estamos dándole mucha importancia a las fichas técnicas y códigos universales de los productos. Completarlos ayudará a los vendedores:

  • Tendrán más exposición en los listados.

  • Tendrán información más organizada en su publicación, y se evitarán preguntas innecesarias.

  • Los datos de sus productos se verán mejor que en la descripción.

  • Además, con esta información crearemos filtros de búsqueda para que los encuentren más fácil.

Sabemos que más ventas para ellos significan más ventas para tí. Por eso, te compartimos una API en la que podrás conocer qué datos les faltan a tus vendedores y así ayudarlos a tener publicaciones más completas.


Contenidos

Glosario

domains Los dominios son familias de productos que comparten características en común. Por ejemplo, todos los “Celulares” tienen pantalla, memoria, etc.
pi Los products identifier son los códigos universales de productos. Entre ellos están el EAN, UPC, JAN, GTIN, ISBN, PART_NUMBER, etc.
ft La ficha técnica del producto es el conjunto de atributos que describen al producto.


¿Cómo conocer el estado de un vendedor?

Para ver las métricas generales de un vendedor, agrupadas por dominio (Celulares, Cámaras digitales, etc), realiza una llamada por seller_id. Si quieres conocer las métricas de un vendedor en relación a un dominio en particular, podrás realizar un llamado por seller_id + domain_id + included_items=true. De esta forma, podrás ver el detalle de las publicaciones de ese dominio. Si prefieres conocer una publicación específica del vendedor, podrás hacer un llamado pasando como parametro el item_id. Consejo: al agregarle include_items=true, puede que el JSON se vuelva muy pesado. Por eso, te recomendamos usarlo junto al filtro domain_id. De esta forma, solo verás las publicaciones de un dominio en particular.

Notas:

  • Para cada dominio, se devolverán los ids de las publicaciones que estén incompletos.

  • Por cada publicación, se devolverán los atributos que faltan completar.

  • Esta funcionalidad sólo está disponible para vendedores que tengan hasta 80.000 items publicados.

Llamada:

 curl -X GET https://api.mercadolibre.com/catalog_quality/status?seller_id={seller_id}&include_items={bool}&v={version}&access_token={access_token}

Ejemplo:

 curl -X GET https://api.mercadolibre.com/catalog_quality/status?seller_id=285621066&include_items=true&v=2&access_token=

Respuesta correcta (code: 200):

{
  "status": {
    "metrics": {
      "pi": {
        "complete_items": 1,
        "complete_attributes": 1,
        "incomplete_attributes": 2
      },
      "ft": {
        "complete_items": 1,
        "complete_attributes": 9,
        "incomplete_attributes": 4
      },
      "all": {
        "complete_items": 1,
        "complete_attributes": 10,
        "incomplete_attributes": 6
      }
    },
    "total_items": 3
  },
  "domains": [
    {
      "domain_id": "MLA-WINES",
      "status": {
        "metrics": {
          "pi": {
            "complete_items": 1,
            "complete_attributes": 1,
            "incomplete_attributes": 0
          },
          "ft": {
            "complete_items": 1,
            "complete_attributes": 3,
            "incomplete_attributes": 0
          },
          "all": {
            "complete_items": 1,
            "complete_attributes": 4,
            "incomplete_attributes": 0
          }
        },
        "total_items": 1
      },
      "items": [
        {
          "item_id": "MLA696982328",
          "domain_id": "MLA-WINES",
          "adoption_status": {
            "pi": {
              "complete": true,
              "attributes": [
                "EAN"
              ],
              "missing_attributes": [
              ]
            },
            "ft": {
              "complete": true,
              "attributes": [
                "BRAND",
                "MODEL",
                "YEAR"
              ],
              "missing_attributes": [
              ]
            },
            "all": {
              "complete": true,
              "attributes": [
                "BRAND",
                "MODEL",
                "YEAR",
                "EAN"
              ],
              "missing_attributes": [
              ]
            }
          }
        }
      ]
    },
    {
      "domain_id": "MLA-MICROWAVES",
      "status": {
        "metrics": {
          "pi": {
            "complete_items": 0,
            "complete_attributes": 0,
            "incomplete_attributes": 1
          },
          "ft": {
            "complete_items": 0,
            "complete_attributes": 6,
            "incomplete_attributes": 2
          },
          "all": {
            "complete_items": 0,
            "complete_attributes": 6,
            "incomplete_attributes": 3
          }
        },
        "total_items": 1
      },
      "items": [
        {
          "item_id": "MLA699311866",
          "domain_id": "MLA-MICROWAVES",
          "adoption_status": {
            "pi": {
              "complete": false,
              "attributes": [
              ],
              "missing_attributes": [
                "GTIN"
              ]
            },
            "ft": {
              "complete": false,
              "attributes": [
                "BRAND",
                "MODEL",
                "VOLUME_CAPACITY",
                "MICROWAVE_TYPE",
                "POWER",
                "CONVECTION"
              ],
              "missing_attributes": [
                "GRILL",
                "TURNTABLE"
              ]
            },
            "all": {
              "complete": false,
              "attributes": [
                "BRAND",
                "MODEL",
                "VOLUME_CAPACITY",
                "MICROWAVE_TYPE",
                "POWER",
                "CONVECTION"
              ],
              "missing_attributes": [
                "GTIN",
                "GRILL",
                "TURNTABLE"
              ]
            }
          }
        }
      ]
    },
    {
      "domain_id": "MLA-GENERAL",
      "status": {
        "metrics": {
          "pi": {
            "complete_items": 0,
            "complete_attributes": 0,
            "incomplete_attributes": 1
          },
          "ft": {
            "complete_items": 0,
            "complete_attributes": 0,
            "incomplete_attributes": 2
          },
          "all": {
            "complete_items": 0,
            "complete_attributes": 0,
            "incomplete_attributes": 3
          }
        },
        "total_items": 1
      },
      "items": [
        {
          "item_id": "MLA693183435",
          "domain_id": "",
          "adoption_status": {
            "pi": {
              "complete": false,
              "attributes": [
              ],
              "missing_attributes": [
                "GTIN"
              ]
            },
            "ft": {
              "complete": false,
              "attributes": [
              ],
              "missing_attributes": [
                "BRAND",
                "MODEL"
              ]
            },
            "all": {
              "complete": false,
              "attributes": [
              ],
              "missing_attributes": [
                "BRAND",
                "MODEL",
                "GTIN"
              ]
            }
          }
        }
      ]
    }
  ]
}

Respuesta con error (400 BAD REQUEST - No se envía seller_id):

{
    "message": "Must provide either item_id, or seller_id, or groups param",
    "code": "bad_request",
    "cause": "",
    "status": 400
}


¿Cómo conocer el estado de completitud de una publicación?

Para conocer la completitud de una publicación, puedes realizar:
Llamada:

curl -X GET https://api.mercadolibre.com/catalog_quality/status?item_id={item_id}&v=3&access_token={ACCESS_TOKEN}

Ejemplo:

curl -X GET https://api.mercadolibre.com/catalog_quality/status?item_id=MLA123456789&v=3?access_token={ACCESS_TOKEN}

Respuesta:

{
    "item_id": "MLA123456789",
    "domain_id": "MLA-KITCHEN_RANGE_HOODS",
    "adoption_status": {
        "pi": {
            "complete": false,
            "attributes": [],
            "missing_attributes": [
                "GTIN"
            ]
        },
        "ft": {
            "complete": false,
            "attributes": [
                "BRAND",
                "MODEL",
                "LINE",
                "RANGE_HOOD_TYPE",
                "RANGE_HOOD_MOUNTING",
                "MATERIAL"
            ],
            "missing_attributes": [
                "DUCTED",
                "SPEED_SETTING",
                "BURNERS_NUMBER",
                "COLOR"
            ]
        },
        "required": {
            "complete": true,
            "attributes": [
                "BRAND",
                "RANGE_HOOD_TYPE"
            ],
            "missing_attributes": []
        },
        "all": {
            "complete": false,
            "attributes": [
                "MODEL",
                "LINE",
                "RANGE_HOOD_TYPE",
                "RANGE_HOOD_MOUNTING",
                "MATERIAL",
                "BRAND"
            ],
            "missing_attributes": [
                "BURNERS_NUMBER",
                "COLOR",
                "GTIN",
                "DUCTED",
                "SPEED_SETTING"
            ]
        },
        "quality_level": 0,
        "quality_reason": "PI_INCORRECT"
    },
    "gmv": 0,
    "buying_mode": "buy_it_now"
}

Respuesta con error (400 BAD REQUEST - No se envía item_id):

{
    "message": "Must provide either item_id, or seller_id, or groups param",
    "code": "bad_request",
    "cause": "",
    "status": 400
}

Parámetros

v (Versión de la API) Si bien este parámetro no es requerido se recomienda indicarlo para asegurar que la integración no sufra fricciones al momento de hacer cambios en la API. Actualmente están disponible las siguientes versiones:
v=0 (formato inicial)
v=1 (retorna un formato de respuesta reducido)
v=2 (soporte a ítems sin dominio). Recomendamos usar esta versión.


seller_id
Este parametro es requerido para identificar al vendedor.


item_id
Este parámetro es requerido para identificar a la publicación.


include_incomplete_items
Con este parámetro podrás incluir en la respuesta, un listado de publicaciones que tengan o sus fichas técnicas o sus códigos de producto incompletos. Dentro de “all”, el atributo incomplete_items tendrá las publicaciones incompletas, ya sea porque le faltan sus códigos o especificaciones en sus fichas técnicas.
Notas: Por defecto toma el valor false.


include_items
Hace referencia al apartado del JSON donde se especifica la granularidad por item.
Nota: Por defecto toma el valor false.


domain_id
Este parámetro es opcional. Es útil cuando se quiere conocer el estado de un solo dominio.
Nota: En caso de no ser utilizado, en la respuesta de la llamada se podrán ver todos.


access_token
El access_token es requerido cuando se hace una llamada vía API.
Nota: En caso que el parámetro seller_id no coincida con el vendedor identificado por el access_token se devolverá un status code 403.


Descripción de campos

pi Identificador de Producto
ft Ficha técnica
required Requeridos
all Todos los atributos
quality_level Nivel de calidad del ítem, el cual puede obtener los valores de 0 cuando no cumple con los requisitos y está perdiendo exposición, y 1 cuando está cumpliendo con los requisitos de calidad.
quality_reason Es la razón por la cual el ítem está perdiendo exposición en los listados.


Especificaciones

Para todos los campos por los que se mide la calidad (pi, ft, required y all) cuentan con las secciones de “complete" en donde se especifican los atributos con los que cuenta y "missing_attributes” para especificar los atributos que le faltan por completar en la publicación.