# Americanas API scraper — americanas.com.br (Brazil): search, browse and full product detail from one of Brazil's largest marketplaces, with the card price, the PIX/a-vista price and the struck list price kept apart, interest-free instalments, the marketplace seller, every competing seller offer, EAN, specifications, variants and images. No account, no browser.

> Search Americanas by keyword. Every product comes with the card price, the PIX price and its discount, the struck list price, the best interest-free instalment plan, the seller (Americanas itself or a marketplace seller), how many sellers offer it, availability, EAN and category. Sort by price, best sellers, newest, discount or name; filter by brand, seller, price range, category path or any facet the site publishes.
> ReefAPI engine `americanas` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/americanas/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /americanas/v1/search — 3 credits
Search Americanas by keyword. Every product comes with the card price, the PIX price and its discount, the struck list price, the best interest-free instalment plan, the seller (Americanas itself or a marketplace seller), how many sellers offer it, availability, EAN and category. Sort by price, best sellers, newest, discount or name; filter by brand, seller, price range, category path or any facet the site publishes.

**Parameters:**
- `query` (string, required) — Words a shopper would type on Americanas (Portuguese).
- `country` (enum, optional, default "br") — Americanas sells in Brazil only (americanas.com.br, BRL). [one of: br]
- `page` (integer, optional, default 1) — Result page, from 1. Americanas serves only the first 2500 products of a result set: (page - 1) x page_size must be below 2500.
- `page_size` (integer, optional, default 20) — Products per page, up to 50.
- `sort` (enum, optional, default "relevance") — Americanas' own sort orders. price_asc / price_desc order by the card price. `discount` is Americanas' own discount ranking: it correlates with but does not exactly equal discount_pct computed from the returned prices (measured 112 of 114 adjacent pairs descending). `name_asc` is ordered by Portuguese collation, so accented names sort as a Brazilian shopper expects. Americanas' 'mais vendidos' is not offered: the source accepts it and returns the relevance order unchanged. [one of: relevance, price_asc, price_desc, newest, discount, name_asc]
- `brand` (string, optional) — One brand, as it appears in the `brand` facet (e.g. mondial, philco).
- `seller` (string, optional) — One marketplace seller, as it appears in the `sellername` facet (e.g. magazine-luiza; americanas-sa = sold by Americanas itself).
- `min_price` (number, optional) — Lowest price in BRL (reais). Americanas applies it to the card price.
- `max_price` (number, optional) — Highest price in BRL (reais). Americanas applies it to the card price.
- `category_path` (string, optional) — Limit to a category path, as in a product's category_path or a americanas.com.br category URL (e.g. eletrodomesticos/fogao).
- `facets` (array, optional) — Extra filters as 'key/value' pairs taken from the `filters` action (e.g. genero/feminino, tamanho/41). Anything the site publishes as a facet.
- `in_stock_only` (boolean, optional, default false) — true drops products Americanas lists as unavailable.
- `max_rotations` (integer, optional, default 3) — How many fresh attempts to make before giving up.

**Returns:** results[]{product_id, sku_id, title, brand, url, image, price_brl (card price), pix_price_brl (the a-vista/PIX price the product page headlines), pix_discount_pct, list_price_brl, discount_pct, currency, installments{count, amount_brl, total_brl, interest_free, label}, seller{id, name, is_americanas}, marketplace, in_stock, offer_count, ean, reference, category, category_path[], promotions[]{name, discount_pct}}, count, total_results, max_reachable_results, page, page_size, has_more, stop_reason, unparsable_rows_dropped, sort, applied_filters, country, currency, query

**Example request body:**
```json
{
  "query": "cafeteira eletrica"
}
```

### POST /americanas/v1/category — 3 credits
Every product in an Americanas category, by category path or category URL, paged, with the same rows, sorts and filters as search.

**Parameters:**
- `category` (string, required) — A category path (eletrodomesticos/fogao) or a americanas.com.br category URL. Up to 4 levels deep.
- `country` (enum, optional, default "br") — Americanas sells in Brazil only (americanas.com.br, BRL). [one of: br]
- `page` (integer, optional, default 1) — Result page, from 1. Americanas serves only the first 2500 products of a result set: (page - 1) x page_size must be below 2500.
- `page_size` (integer, optional, default 20) — Products per page, up to 50.
- `sort` (enum, optional, default "relevance") — Americanas' own sort orders. price_asc / price_desc order by the card price. `discount` is Americanas' own discount ranking: it correlates with but does not exactly equal discount_pct computed from the returned prices (measured 112 of 114 adjacent pairs descending). `name_asc` is ordered by Portuguese collation, so accented names sort as a Brazilian shopper expects. Americanas' 'mais vendidos' is not offered: the source accepts it and returns the relevance order unchanged. [one of: relevance, price_asc, price_desc, newest, discount, name_asc]
- `brand` (string, optional) — One brand, as it appears in the `brand` facet (e.g. mondial, philco).
- `seller` (string, optional) — One marketplace seller, as it appears in the `sellername` facet (e.g. magazine-luiza; americanas-sa = sold by Americanas itself).
- `min_price` (number, optional) — Lowest price in BRL (reais). Americanas applies it to the card price.
- `max_price` (number, optional) — Highest price in BRL (reais). Americanas applies it to the card price.
- `facets` (array, optional) — Extra filters as 'key/value' pairs taken from the `filters` action (e.g. genero/feminino, tamanho/41). Anything the site publishes as a facet.
- `in_stock_only` (boolean, optional, default false) — true drops products Americanas lists as unavailable.
- `max_rotations` (integer, optional, default 3) — How many fresh attempts to make before giving up.

**Returns:** results[]{product_id, sku_id, title, brand, url, image, price_brl (card price), pix_price_brl (the a-vista/PIX price the product page headlines), pix_discount_pct, list_price_brl, discount_pct, currency, installments{count, amount_brl, total_brl, interest_free, label}, seller{id, name, is_americanas}, marketplace, in_stock, offer_count, ean, reference, category, category_path[], promotions[]{name, discount_pct}}, count, total_results, max_reachable_results, page, page_size, has_more, stop_reason, unparsable_rows_dropped, sort, applied_filters, country, currency, category_path

### POST /americanas/v1/seller/products — 3 credits
Everything a named Americanas marketplace seller lists, paged, with the same rows, sorts and filters as search. Seller names come from the `filters` action's sellername facet.

**Parameters:**
- `seller` (string, required) — The seller name as it appears in the sellername facet.
- `country` (enum, optional, default "br") — Americanas sells in Brazil only (americanas.com.br, BRL). [one of: br]
- `query` (string, optional) — The keyword whose filters you want. Omit it to get a category's filters.
- `page` (integer, optional, default 1) — Result page, from 1. Americanas serves only the first 2500 products of a result set: (page - 1) x page_size must be below 2500.
- `page_size` (integer, optional, default 20) — Products per page, up to 50.
- `sort` (enum, optional, default "relevance") — Americanas' own sort orders. price_asc / price_desc order by the card price. `discount` is Americanas' own discount ranking: it correlates with but does not exactly equal discount_pct computed from the returned prices (measured 112 of 114 adjacent pairs descending). `name_asc` is ordered by Portuguese collation, so accented names sort as a Brazilian shopper expects. Americanas' 'mais vendidos' is not offered: the source accepts it and returns the relevance order unchanged. [one of: relevance, price_asc, price_desc, newest, discount, name_asc]
- `brand` (string, optional) — One brand, as it appears in the `brand` facet (e.g. mondial, philco).
- `min_price` (number, optional) — Lowest price in BRL (reais). Americanas applies it to the card price.
- `max_price` (number, optional) — Highest price in BRL (reais). Americanas applies it to the card price.
- `category_path` (string, optional) — Limit to a category path, as in a product's category_path or a americanas.com.br category URL (e.g. eletrodomesticos/fogao).
- `facets` (array, optional) — Extra filters as 'key/value' pairs taken from the `filters` action (e.g. genero/feminino, tamanho/41). Anything the site publishes as a facet.
- `in_stock_only` (boolean, optional, default false) — true drops products Americanas lists as unavailable.
- `max_rotations` (integer, optional, default 3) — How many fresh attempts to make before giving up.

**Returns:** results[]{product_id, sku_id, title, brand, url, image, price_brl (card price), pix_price_brl (the a-vista/PIX price the product page headlines), pix_discount_pct, list_price_brl, discount_pct, currency, installments{count, amount_brl, total_brl, interest_free, label}, seller{id, name, is_americanas}, marketplace, in_stock, offer_count, ean, reference, category, category_path[], promotions[]{name, discount_pct}}, count, total_results, max_reachable_results, page, page_size, has_more, stop_reason, unparsable_rows_dropped, sort, applied_filters, country, currency, seller

### POST /americanas/v1/product/detail — 1 credit
The full Americanas product record by id or URL: title, brand, EAN, reference, the card price, the PIX price and its discount, the struck list price, the best interest-free instalment plan, the seller, EVERY competing seller offer with its own prices, availability, description, specifications, images, variants with their own ids and prices, category breadcrumb and release date.

**Parameters:**
- `product_id` (string, required) — An Americanas product id (the trailing number of a product URL) or the product URL itself.
- `country` (enum, optional, default "br") — Americanas sells in Brazil only (americanas.com.br, BRL). [one of: br]
- `max_rotations` (integer, optional, default 3) — How many fresh attempts to make before giving up.

**Returns:** product{product_id, sku_id, title, brand, url, image, price_brl (card price), pix_price_brl (the a-vista/PIX price the product page headlines), pix_discount_pct, list_price_brl, discount_pct, currency, installments{count, amount_brl, total_brl, interest_free, label}, seller{id, name, is_americanas}, marketplace, in_stock, offer_count, ean, reference, category, category_path[], promotions[]{name, discount_pct}, description, specifications{name: value}, images[], variants[]{sku_id, name, ean, attributes, in_stock, price_brl, pix_price_brl}, variant_count, offers[]{seller{}, sku_id, price_brl, pix_price_brl, list_price_brl, installments{}, in_stock}, category_id, release_date, meta_description}, country, currency

**Example request body:**
```json
{
  "product_id": "4895445"
}
```

### POST /americanas/v1/product/batch — 5 credits
Up to 10 Americanas products in one call, each the same full record as product/detail. Ids that do not resolve are reported in not_found[] instead of failing the whole call.

**Parameters:**
- `product_ids` (array, required) — Up to 10 Americanas product ids or product URLs in one call.
- `country` (enum, optional, default "br") — Americanas sells in Brazil only (americanas.com.br, BRL). [one of: br]
- `max_rotations` (integer, optional, default 3) — How many fresh attempts to make before giving up.

**Returns:** products[]{…the product/detail shape…}, count, requested, not_found[], country, currency

### POST /americanas/v1/filters — 1 credit
The filters Americanas itself offers for a keyword or a category — brands, sellers, price range, category tree and the per-category attributes (size, colour, gender…). Feed any of them back into search as `facets`.

**Parameters:**
- `query` (string, optional) — The keyword whose filters you want. Omit it to get a category's filters.
- `category` (string, optional) — A category path to get that category's filters.
- `country` (enum, optional, default "br") — Americanas sells in Brazil only (americanas.com.br, BRL). [one of: br]
- `max_rotations` (integer, optional, default 3) — How many fresh attempts to make before giving up.

**Returns:** filters[]{key, label, type, values[]{value, label, count}}, price_range{min, max}, count, query, category_path, country

### POST /americanas/v1/search/suggest — 0 credits
Americanas' own search-box completions for what a shopper has typed, with how often each term is searched and the department it belongs to.

**Parameters:**
- `query` (string, required) — What a shopper has typed so far.
- `country` (enum, optional, default "br") — Americanas sells in Brazil only (americanas.com.br, BRL). [one of: br]
- `max_rotations` (integer, optional, default 3) — How many fresh attempts to make before giving up.

**Returns:** suggestions[]{term, search_count, department, position}, count, query, country

**Example request body:**
```json
{
  "query": "cafeteira eletrica"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=americanas
- Human docs page: https://reefapi.com/docs/americanas
- Overview page: https://reefapi.com/americanas-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt