Saltar al contenido principal
Busca productos en la tienda Ulta (ulta.com) y lee sus páginas de producto mediante la API de tareas asíncronas. Envía COMMERCE_SERP con site ulta para recibir los productos que muestra una búsqueda, en el orden de la tienda, o COMMERCE_PRODUCT con la url de un producto para leer ese producto. Cada búsqueda o página de producto completada cuesta 0.5 créditos.

Búsqueda

Envía la tarea y luego consulta GET /v1/async/task/{id} o recibe su webhook. Consulta Tareas asíncronas.

Parámetros

  • site: Obligatorio. ulta.
  • query: Obligatorio. Consulta de búsqueda, de 1 a 500 caracteres.
  • limit: Entero opcional de 1 a 40, con 20 por defecto.
  • country: Opcional. Por defecto, US, el país de la tienda. Cualquier otro país se rechaza con 422 REGION_UNSUPPORTED.
Solo se aceptan los campos de payload enumerados arriba. Omite include: incluso include: {} devuelve 422 VALIDATION_ERROR en payload.include antes de reservar créditos.

Ejemplo de respuesta

Campos del resultado

  • site, query y country repiten la solicitud. returnedCount es el número de elementos de products.
  • Cada producto incluye rank, productId, title y url. productId es el ID de producto propio de la tienda. rank sigue el orden predeterminado de la tienda, y se omiten los anuncios que la tienda marca como patrocinados.
  • price, rating, reviewCount, imageUrl y brand aparecen cuando la página de resultados los muestra. price es un número en la currency del producto (ISO 4217); cuando los tamaños tienen precios distintos, es el más bajo.
  • rating usa una escala de cinco puntos. Los números de reseñas abreviados, como 999+, se omiten.
  • Cada búsqueda devuelve productos de la primera página de resultados de la tienda. Ulta envía algunos nombres de marca a la página de la marca, y los productos salen de esa página.

Página de producto

Parámetros

  • url: Obligatorio. Una página de producto de la tienda Ulta, de hasta 2.048 caracteres: ulta.com/p/{name}-{id}. Las url de producto que devuelve una búsqueda sirven tal cual. Los parámetros que no afectan al resultado, como los códigos de seguimiento, se quitan antes de leer la página.
  • country: Opcional. Por defecto, US, el país de la página. Cualquier otro país se rechaza con 422 REGION_UNSUPPORTED.
Solo se aceptan los campos de payload enumerados arriba. Omite include: incluso include: {} devuelve 422 VALIDATION_ERROR en payload.include antes de reservar créditos.

Ejemplo de respuesta

Campos del resultado

  • site, country, url y productId identifican la página. url es la página que se leyó, y productId coincide con el que devuelve una búsqueda.
  • title siempre está presente. brand, price, currency, inStock, rating, reviewCount, images, description, descriptionImages, specs, options, categories y gtin aparecen cuando la página los muestra.
  • price es lo que paga un comprador tal como la página lo muestra al abrirse, antes de cupones y envío, en currency (ISO 4217). inStock es la disponibilidad del producto.
  • rating usa una escala de cinco puntos con dos decimales. reviewCount es el número de reseñas.
  • images lista hasta 30 fotos de la galería del producto, en el orden de la página.
  • description es texto plano con una línea por párrafo, de hasta 10.000 caracteres; el texto que solo aparece dentro de imágenes no se incluye.
  • descriptionImages lista hasta 300 imágenes de la descripción del producto, en el orden de la página. Se incluyen los banners y avisos que los vendedores ponen en su descripción, y el texto dentro de las imágenes no se lee.
  • specs lista hasta 100 pares { name, value } de los detalles del producto. options lista hasta 20 opciones, como talla o color, cada una con hasta 100 values; los demás campos describen la opción con la que se abre la página. categories va de la categoría más amplia a la más concreta, con hasta 10 niveles. gtin es el UPC, EAN o JAN que indica la página.

Errores y facturación

  • Una búsqueda que no devuelve productos termina como tarea fallida.
  • Una página de producto que la tienda responde con 404 o 410, como un producto retirado, termina la tarea con PAGE_UNAVAILABLE, y el mensaje incluye la respuesta de la tienda. Si la tienda rechaza la lectura con 403, 412, 429 o 435, la tarea espera y vuelve a consultar durante un máximo de 6 minutos. Las demás lecturas fallidas, y un rechazo que dura más, terminan con ENGINE_NO_RESULT.
  • Solo se cobran las tareas completadas: 0.5 créditos por búsqueda o página de producto.

Relacionado