Saltar para o conteúdo principal
Busque produtos na loja Ulta (ulta.com) e leia as páginas de produto dela pela API de tarefas assíncronas. Envie COMMERCE_SERP com site ulta para receber os produtos que uma busca mostra, na ordem da loja, ou COMMERCE_PRODUCT com a url de um produto para ler esse produto. Cada busca ou página de produto concluída custa 0.5 crédito.

Busca

Envie a tarefa e depois consulte GET /v1/async/task/{id} ou receba o webhook. Veja Tarefas assíncronas.

Parâmetros

  • site: Obrigatório. ulta.
  • query: Obrigatório. Termo de busca, de 1 a 500 caracteres.
  • limit: Inteiro opcional de 1 a 40, com padrão 20.
  • country: Opcional. O padrão é US, o país da loja. Qualquer outro país é recusado com 422 REGION_UNSUPPORTED.
Só os campos de payload listados acima são aceitos. Omita include: até include: {} retorna 422 VALIDATION_ERROR em payload.include antes da reserva de créditos.

Exemplo de resposta

Campos do resultado

  • site, query e country repetem a requisição. returnedCount é o número de itens em products.
  • Cada produto inclui rank, productId, title e url. productId é o ID de produto da própria loja. rank segue a ordem padrão da loja, e os anúncios que a loja marca como patrocinados ficam de fora.
  • price, rating, reviewCount, imageUrl e brand aparecem quando a página de resultados os mostra. price é um número na currency do produto (ISO 4217); quando os tamanhos têm preços diferentes, é o menor.
  • rating usa uma escala de cinco pontos. Números de avaliações abreviados, como 999+, ficam de fora.
  • Cada busca retorna produtos da primeira página de resultados da loja. A Ulta envia alguns nomes de marca para a página da marca, e os produtos vêm dessa página.

Página de produto

Parâmetros

  • url: Obrigatório. Uma página de produto da loja Ulta, com até 2.048 caracteres: ulta.com/p/{name}-{id}. As url de produto que uma busca retorna funcionam como estão. Os parâmetros que não afetam o resultado, como códigos de rastreamento, são removidos antes da leitura.
  • country: Opcional. O padrão é US, o país da página. Qualquer outro país é recusado com 422 REGION_UNSUPPORTED.
Só os campos de payload listados acima são aceitos. Omita include: até include: {} retorna 422 VALIDATION_ERROR em payload.include antes da reserva de créditos.

Exemplo de resposta

Campos do resultado

  • site, country, url e productId identificam a página. url é a página lida, e productId é o mesmo que uma busca retorna.
  • title sempre aparece. brand, price, currency, inStock, rating, reviewCount, images, description, descriptionImages, specs, options, categories e gtin aparecem quando a página os mostra.
  • price é o que um comprador paga conforme a página mostra ao abrir, antes de cupons e frete, em currency (ISO 4217). inStock é a disponibilidade do produto.
  • rating usa uma escala de cinco pontos com duas casas decimais. reviewCount é o número de avaliações.
  • images lista até 30 fotos da galeria do produto, na ordem da página.
  • description é texto simples com uma linha por parágrafo, com até 10.000 caracteres; o texto que só aparece dentro de imagens não é incluído.
  • descriptionImages lista até 300 imagens da descrição do produto, na ordem da página. Banners e avisos que os vendedores colocam na descrição vêm junto, e o texto dentro das imagens não é lido.
  • specs lista até 100 pares { name, value } dos detalhes do produto. options lista até 20 escolhas, como tamanho ou cor, cada uma com até 100 values; os demais campos descrevem a escolha com que a página abre. categories vai da categoria mais ampla à mais específica, com até 10 níveis. gtin é o UPC, EAN ou JAN que a página informa.

Erros e cobrança

  • Uma busca que não retorna produtos termina como tarefa com falha.
  • Uma página de produto que a loja responde com 404 ou 410, como um produto removido, encerra a tarefa com PAGE_UNAVAILABLE, e a mensagem traz a resposta da loja. Se a loja recusar a leitura com 403, 412, 429 ou 435, a tarefa espera e tenta de novo por até 6 minutos. As demais leituras com falha, e uma recusa que dure mais, terminam com ENGINE_NO_RESULT.
  • Só as tarefas concluídas são cobradas: 0.5 crédito por busca ou página de produto.

Relacionado