> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon API

> Busque produtos na loja Amazon e leia as páginas de produto dela em JSON: posições com preços, notas e número de avaliações na busca, e preço, estoque, vendedor, imagens, especificações e opções em cada página de produto.

Busque produtos na loja Amazon (amazon.com) e leia as páginas de produto dela pela API de tarefas assíncronas. Envie `COMMERCE_SERP` com `site` `amazon` 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 **1 crédito**.

## Busca

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_SERP", "payload": { "site": "amazon", "query": "wireless earbuds", "limit": 3 } }'
```

Envie a tarefa e depois consulte `GET /v1/async/task/{id}` ou receba o webhook. Veja [Tarefas assíncronas](https://docs.querying.ai/pt/concepts/async-tasks.md).

### Parâmetros

* `site`: Obrigatório. `amazon`.
* `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

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "query": "wireless earbuds",
  "country": "US",
  "returnedCount": 3,
  "products": [
    {
      "rank": 1,
      "productId": "B0HJTS6LXB",
      "title": "Wireless Earbuds, 2026 Bluetooth 5.4 Headphones Bass Stereo Ear Buds with Noise Cancelling Mic, LED Display in Ear Earphones 50H Playtime Ear Buds, IP7 Waterproof for Laptop Pad Phones Dark Black",
      "url": "https://www.amazon.com/dp/B0HJTS6LXB",
      "price": 19.99,
      "currency": "USD",
      "rating": 4.6,
      "reviewCount": 656,
      "imageUrl": "https://m.media-amazon.com/images/I/61aSuH86kYL._AC_UY218_.jpg"
    },
    {
      "rank": 2,
      "productId": "B0FQFB8FMG",
      "title": "Apple AirPods Pro 3 Wireless Earbuds with Active Noise Cancellation",
      "url": "https://www.amazon.com/dp/B0FQFB8FMG",
      "price": 179,
      "currency": "USD",
      "rating": 4.4,
      "reviewCount": 18076,
      "imageUrl": "https://m.media-amazon.com/images/I/61solmQSSlL._AC_UY218_.jpg"
    },
    {
      "rank": 3,
      "productId": "B0BQPNMXQV",
      "title": "JBL Vibe Beam - True Wireless Earbuds - Black",
      "url": "https://www.amazon.com/dp/B0BQPNMXQV",
      "price": 29.95,
      "currency": "USD",
      "rating": 4.2,
      "reviewCount": 41710,
      "imageUrl": "https://m.media-amazon.com/images/I/41+1Csr1pSL._AC_UY218_.jpg"
    }
  ]
}
```

### 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 ASIN. `rank` segue a ordem padrão da loja, e os anúncios que a loja marca como patrocinados ficam de fora.
* `price`, `rating`, `reviewCount` e `imageUrl` 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. Uma mesma busca na Amazon pode listar mais de uma moeda.
* `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.

## Página de produto

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_PRODUCT", "payload": { "url": "https://www.amazon.com/dp/B0HJTS6LXB" } }'
```

### Parâmetros

* `url`: Obrigatório. Uma página de produto da loja Amazon, com até 2.048 caracteres: `amazon.com/dp/{ASIN}` ou `amazon.co.jp/dp/{ASIN}`. 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. Outros endereços da mesma página também funcionam, como `/gp/product/{ASIN}`.
* `country`: Opcional. O padrão é o país da página: `US` em amazon.com e `JP` em amazon.co.jp. 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

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "country": "US",
  "url": "https://www.amazon.com/dp/B0HJTS6LXB",
  "productId": "B0HJTS6LXB",
  "title": "Wireless Earbuds, 2026 Bluetooth 5.4 Headphones Bass Stereo Ear Buds with Noise Cancelling Mic, LED Display in Ear Earphones 50H Playtime Ear Buds, IP7 Waterproof for Laptop Pad Phones Dark Black",
  "brand": "XIAOWTEK",
  "price": 19.99,
  "listPrice": 199.99,
  "currency": "USD",
  "inStock": true,
  "seller": "duanyuekj",
  "rating": 4.6,
  "reviewCount": 656,
  "images": [
    "https://m.media-amazon.com/images/I/61aSuH86kYL._AC_SL1500_.jpg",
    "https://m.media-amazon.com/images/I/614SJ1xXHDL._AC_SL1500_.jpg"
  ],
  "description": "LED Power Display and 50H Playback: Dual digital LED power display outside of the case is to show the power level for charging case and earbuds. When charging for the case, the LED light will start…",
  "descriptionImages": [
    "https://m.media-amazon.com/images/S/aplus-media-library-service-media/bd0bc2d5-cf30-4f89-bb94-79fa935a35c4.__CR0,0,1464,600_PT0_SX1464_V1___.jpg",
    "https://m.media-amazon.com/images/S/aplus-media-library-service-media/a0abce46-fbc8-4054-9705-77153bb852a8.__CR0,0,1464,600_PT0_SX1464_V1___.jpg"
  ],
  "specs": [
    { "name": "Brand", "value": "XIAOWTEK" },
    { "name": "Color", "value": "Dark Black" },
    { "name": "Ear Placement", "value": "In Ear" }
  ],
  "options": [{ "name": "Color", "values": ["Blue", "Carbon Black", "Dark Black", "Pink"] }],
  "categories": [
    "Electronics",
    "Headphones, Earbuds & Accessories",
    "Headphones & Earbuds",
    "Earbud Headphones"
  ]
}
```

### 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`, `listPrice`, `currency`, `inStock`, `seller`, `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). `listPrice` é o preço normal que a página risca, presente quando é maior que `price`. `inStock` é a disponibilidade do produto. `seller` é o lojista que o vende. As páginas da amazon.co.jp retornam `country` `JP` e preços em `JPY`. Quando a Amazon não escolhe uma oferta em destaque para um produto, a página não mostra preço, então `price`, `currency`, `seller` e `inStock` vêm do primeiro vendedor com preço na lista de ofertas 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: 1 crédito por busca ou página de produto.

## Relacionado

* [Walmart](https://docs.querying.ai/pt/engines/walmart.md)
* [Target](https://docs.querying.ai/pt/engines/target.md)
* [eBay](https://docs.querying.ai/pt/engines/ebay.md)
* [Todas as lojas do Commerce](https://docs.querying.ai/pt/engines/overview.md#commerce)
* [Créditos e limites](https://docs.querying.ai/pt/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.