# decoindex

> Storefronts an agent can read. Take any VTEX or Shopify storefront URL, put
> `decoindex.com/` in front of the domain, and get normalized Markdown instead of
> a megabyte of client-rendered HTML. Resolved on demand from the merchant's own
> public API, so any URL works on the first request.

## The whole convention

```
https://www.farmrio.com.br/moda-feminina
https://decoindex.com/farmrio.com.br/moda-feminina
```

- `https://decoindex.com/{domain}` — start here. The storefront overview: what the merchant
  says it is, its categories, its best sellers, and the terms its own shoppers
  search for. One request, and you know whether this store is worth exploring.
- Any storefront path works the same way. Product pages, category listings.
- `?page=N` paginates. `?sort=price_asc` orders the whole catalog, not just the
  page you were handed (also price_desc, name_asc, name_desc, discount, new).
- `https://decoindex.com/{domain}/search?q={words}` searches that storefront. `/busca/{words}`
  works too — it is the search path the store itself uses.
- Append `.json` to any of these for the same document, structured.

## Storefronts that work today

Some of the largest retailers in Brazil, roughly by traffic. Each was checked
end to end when this list was written — overview, search, a price-ordered
listing, and a product page with a price on it. Start at any of them.

- https://decoindex.com/cea.com.br — C&A. Fashion, and the heaviest page we know of: 5.7 MB of HTML.
- https://decoindex.com/paguemenos.com.br — Pague Menos. Pharmacy.
- https://decoindex.com/americanas.com.br — Americanas. General retailer, 58 top-level categories.
- https://decoindex.com/farmrio.com.br — Farm Rio. Fashion; overview carries best sellers and top searches.
- https://decoindex.com/hering.com.br — Hering. Fashion, 117 categories.
- https://decoindex.com/drogariasaopaulo.com.br — Drogaria São Paulo. Pharmacy, 1,600 categories.
- https://decoindex.com/lojastorra.com.br — Lojas Torra. Fashion.
- https://decoindex.com/vivara.com.br — Vivara. Jewellery.
- https://decoindex.com/lebiscuit.com.br — Le Biscuit. Homeware.
- https://decoindex.com/fila.com.br — Fila. Footwear and sportswear.
- https://decoindex.com/osklen.com.br — Osklen. Rio lifestyle brand.
- https://decoindex.com/bagaggio.com.br — Bagaggio. Luggage.
- https://decoindex.com/technos.com.br — Technos. Watches.
- https://decoindex.com/allbirds.com — Allbirds. A Shopify store in the US: same convention, other platform.

The same URL shapes work on every one of them:

- https://decoindex.com/americanas.com.br/search?q=playstation%205 — search a storefront
- https://decoindex.com/cea.com.br/moda-feminina?sort=price_asc — cheapest first, across the whole category
- https://decoindex.com/farmrio.com.br/busca/vestido — the store's own search path also works

Product pages are reached from any listing: every row carries a Details link.
They are not listed here by hand, because a hardcoded SKU is a dead link the
day it sells out.

This list is checked, not guaranteed. A storefront can change or start refusing
us at any time; if one of these is broken, the feedback endpoint below is the
fastest way to tell us.

## What a product page gives you

Frontmatter with the canonical URL, platform, currency, observed price and
availability. Then every variant with its own SKU, price, stock and a cart link
that builds a cart on the merchant's own checkout — so a read can end in a
purchase a person completes, not just a description.

## What is not published

Live stock for a chosen variant, the final price after cart promotions and
coupons, delivery dates for an address, and anything priced for one shopper.
Those belong to the merchant. Every document repeats this in its own body, so a
page read in isolation still knows what it may promise.

## Telling us something is wrong

The only way we learn a document is bad:

```
curl -X POST https://decoindex.com/feedback -H 'content-type: application/json' \
  -d '{"url":"<the decoindex URL>","kind":"wrong_data","message":"what you expected"}'
```

No authentication. `kind`: wrong_data, missing, broken, unsupported, other.

## Notes

- Supported platforms: VTEX and Shopify.
- The merchant's own site is always canonical; every response says so.
- Cost of reading a storefront both ways: https://decoindex.com/benchmark
- Merchants: https://decoindex.com/opt-out