{"openapi":"3.1.0","info":{"title":"brmarket — Brazilian marketplace product search (x402)","version":"1.0.0","description":"Search and compare products across Brazilian marketplaces (Mercado Livre, Shopee, AliExpress) in one call, with normalized BRL prices in integer cents and canonical + affiliate links. Every response carries per-marketplace `sources` state and `data_as_of`, so a degraded marketplace is always visible. Prices are captured live and change constantly — confirm on the marketplace before purchasing.","x-guidance":"Use this API to find and compare products on Brazilian marketplaces. (1) GET /v1/search?q= — one call fans out to Mercado Livre, Shopee and AliExpress and returns ONE normalized shape: priceCents (always BRL, integer), url, affiliateUrl, shippingFree, rating, soldCount, dataAsOf. Sorted cheapest-first by default; cap 20 per page. (2) POST /v1/search/image — search from a product PHOTO (upload or URL); `interpreted_query` tells you exactly what was searched, so a misread photo is visible rather than mysterious. ALWAYS read `sources`: a marketplace may be error/timeout/not_configured, and a short result list may mean a marketplace was down rather than the market being thin. `priceCents` is the cheapest offer we SAMPLED, never a claim about the cheapest on the marketplace — no upstream here can promise that. GET /v1/preview/search?q= is FREE (1 result, canonical link only). Prices are per call; invalid input is rejected for free and a failed call is never charged.","contact":{"email":"contato@thomenz.me"}},"servers":[{"url":"https://brmarket.thomenz.me"}],"paths":{"/v1/search":{"get":{"operationId":"searchProducts","summary":"Search & compare products across Brazilian marketplaces","description":"Search and compare products across Brazilian marketplaces (Mercado Livre, Shopee, AliExpress) in one call: normalized BRL prices in cents, canonical + affiliate links, free-shipping flag, rating and sold count. Per-marketplace `sources` state and `data_as_of` ship with every response, so a degraded or unconfigured marketplace is visible, never silent.","tags":["Product search"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"q","in":"query","required":true,"description":"What to search for.","schema":{"type":"string","minLength":2,"description":"What to search for.","examples":["iphone 14 pro"]},"example":"iphone 14 pro"},{"name":"limit","in":"query","required":false,"description":"Results in the merged page. Cap 20.","schema":{"type":"integer","minimum":1,"maximum":20,"default":10,"description":"Results in the merged page. Cap 20."}},{"name":"sort","in":"query","required":false,"description":"Default is price_asc — cheapest first.","schema":{"enum":["price_asc","price_desc","relevance"],"default":"price_asc","description":"Default is price_asc — cheapest first."}},{"name":"min_price","in":"query","required":false,"description":"Minimum price in BRL (e.g. 199.90).","schema":{"type":"number","minimum":0,"description":"Minimum price in BRL (e.g. 199.90)."}},{"name":"max_price","in":"query","required":false,"description":"Maximum price in BRL.","schema":{"type":"number","minimum":0,"description":"Maximum price in BRL."}},{"name":"marketplace","in":"query","required":false,"description":"Comma-separated subset to query: mercadolivre, shopee, aliexpress. Default: all.","schema":{"type":"string","description":"Comma-separated subset to query: mercadolivre, shopee, aliexpress. Default: all.","examples":["mercadolivre,shopee"]},"example":"mercadolivre,shopee"},{"name":"uf","in":"query","required":false,"description":"Buyer's 2-letter Brazilian state, for the ICMS rate in landed-price estimates. Default: 20% (ceiling).","schema":{"type":"string","description":"Buyer's 2-letter Brazilian state, for the ICMS rate in landed-price estimates. Default: 20% (ceiling).","examples":["SP"]},"example":"SP"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{"query":"iphone 14 pro","results":[{"marketplace":"mercadolivre","productId":"MLB19615350","title":"Apple iPhone 14 Pro 512 GB Dourado","priceCents":300000,"url":"https://produto.mercadolivre.com.br/MLB-4904112231","affiliateUrl":null,"imageUrl":"https://http2.mlstatic.com/D_NQ_NP_2X_123456-MLB.webp","seller":{"id":"182736450","name":null,"officialStore":false},"shippingFree":true,"dataAsOf":"2026-07-17T13:30:34.360Z"},{"marketplace":"aliexpress","productId":"1005011820157510","title":"Excellent A8 Wireless Bluetooth Earbuds Active Noise Cancellation","priceCents":8919,"originalPriceCents":20270,"url":"https://www.aliexpress.com/item/1005011820157510.html","affiliateUrl":"https://s.click.aliexpress.com/e/_c2ROmufZ","imageUrl":"https://ae-pic-a1.aliexpress-media.com/kf/S9797cb68d7f54af6a1e0544043443f47J.jpg","seller":{"id":"1105334068","name":"Shop1105334068 Store","officialStore":false},"rating":4.85,"soldCount":84,"dataAsOf":"2026-07-17T13:30:34.360Z"}],"sources":{"mercadolivre":"ok","shopee":"not_configured","aliexpress":"ok"},"count":2,"data_as_of":"2026-07-17T13:30:34.360Z","disclaimer":"Prices and availability are captured live from each marketplace at the time of the call and change constantly — `dataAsOf` states exactly when. Always confirm on the marketplace before purchasing. Links may be affiliate links."}}}},"402":{"description":"Payment Required (x402). Pay to receive the response."}}}},"/v1/search/image":{"post":{"operationId":"searchProductsByImage","summary":"Search Brazilian marketplaces from a product photo","description":"Search Brazilian marketplaces from a PRODUCT PHOTO. Send an image (multipart upload or URL); a vision model reads the brand, model and attributes off it, and the resulting query runs across Mercado Livre, Shopee and AliExpress. Returns the same normalized offers as /v1/search, plus `interpreted_query` — the exact text that was searched, so a misread photo is visible.","tags":["Product search"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Send EITHER this JSON body with `image_url`, OR a multipart/form-data upload with an `image` file part (JPEG/PNG/WebP, max 5MB). Every /v1/search filter also applies here.","properties":{"image_url":{"type":"string","format":"uri","description":"Public https URL of the product photo. JPEG/PNG/WebP, max 5MB.","examples":["https://example.com/photo.jpg"]},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10},"sort":{"enum":["price_asc","price_desc","relevance"],"default":"price_asc"},"min_price":{"type":"number","minimum":0},"max_price":{"type":"number","minimum":0},"marketplace":{"type":"string","description":"Comma-separated subset. Default: all."},"uf":{"type":"string","description":"Buyer's 2-letter Brazilian state, for the ICMS rate. Default: 20%."}},"required":["image_url"]},"example":{"image_url":"https://example.com/photo.jpg","limit":5}},"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary","description":"JPEG/PNG/WebP, max 5MB."},"limit":{"type":"integer","minimum":1,"maximum":20},"sort":{"enum":["price_asc","price_desc","relevance"]},"marketplace":{"type":"string"}},"required":["image"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{"interpreted_query":"Apple iPhone 14 Pro 128GB smartphone roxo","query":"Apple iPhone 14 Pro 128GB smartphone roxo","results":[{"marketplace":"mercadolivre","productId":"MLB19615350","title":"Apple iPhone 14 Pro 512 GB Dourado","priceCents":300000,"url":"https://produto.mercadolivre.com.br/MLB-4904112231","affiliateUrl":null,"imageUrl":"https://http2.mlstatic.com/D_NQ_NP_2X_123456-MLB.webp","seller":{"id":"182736450","name":null,"officialStore":false},"shippingFree":true,"dataAsOf":"2026-07-17T13:30:34.360Z"},{"marketplace":"aliexpress","productId":"1005011820157510","title":"Excellent A8 Wireless Bluetooth Earbuds Active Noise Cancellation","priceCents":8919,"originalPriceCents":20270,"url":"https://www.aliexpress.com/item/1005011820157510.html","affiliateUrl":"https://s.click.aliexpress.com/e/_c2ROmufZ","imageUrl":"https://ae-pic-a1.aliexpress-media.com/kf/S9797cb68d7f54af6a1e0544043443f47J.jpg","seller":{"id":"1105334068","name":"Shop1105334068 Store","officialStore":false},"rating":4.85,"soldCount":84,"dataAsOf":"2026-07-17T13:30:34.360Z"}],"sources":{"mercadolivre":"ok","shopee":"not_configured","aliexpress":"ok"},"count":2,"data_as_of":"2026-07-17T13:30:34.360Z","disclaimer":"Prices and availability are captured live from each marketplace at the time of the call and change constantly — `dataAsOf` states exactly when. Always confirm on the marketplace before purchasing. Links may be affiliate links."}}}},"402":{"description":"Payment Required (x402). Pay to receive the response."}}}},"/v1/compare":{"post":{"operationId":"compareProduct","summary":"Paste a product link → find the same item cheaper across marketplaces","description":"Paste a product URL from ANY store; the API identifies the product and returns the same or equivalent item CHEAPER across Mercado Livre, Shopee and AliExpress. Each candidate carries a `match_confidence` (no cross-marketplace barcode exists, so a match is never claimed identical) and a landed-price estimate (import tax included for international offers, labeled). Our marketplaces resolve by API; other stores via a page read that falls back to the URL text.","tags":["Product search"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.040000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Product URL from any store (Mercado Livre, Shopee, AliExpress, Amazon, Magalu, Kabum, ...). Short links are expanded.","examples":["https://www.mercadolivre.com.br/x/p/MLB42996179"]},"uf":{"type":"string","description":"Buyer's 2-letter Brazilian state, for the ICMS rate in the landed-price estimate. Default: 20%.","examples":["SP"]},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10,"description":"How many cheaper candidates to return. Cap 20."}},"required":["url"]},"example":{"url":"https://www.mercadolivre.com.br/x/p/MLB42996179","uf":"SP"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{"compare":true,"source":{"title":"Painel Central Inteligente Maxpanel - Novadigital MPN-10","brand":"Novadigital","model":"MPN-10","priceCents":250268,"marketplace":"magazineluiza","url":"https://www.magazineluiza.com.br/painel-central-inteligente-maxpanel-novadigital/p/ad3g3a21d1/","resolved_via":"gemini"},"query":"novadigital mpn 10 painel central inteligente maxpanel","results":[{"marketplace":"aliexpress","productId":"1005011820157510","title":"Novadigital MaxPanel MPN-10 Zigbee Smart Home Control Panel","priceCents":187848,"originalPriceCents":20270,"url":"https://www.aliexpress.com/item/1005011820157510.html","affiliateUrl":"https://s.click.aliexpress.com/e/_c2ROmufZ","imageUrl":"https://ae-pic-a1.aliexpress-media.com/kf/S9797cb68d7f54af6a1e0544043443f47J.jpg","seller":{"id":"1105334068","name":"Shop1105334068 Store","officialStore":false},"rating":4.85,"soldCount":84,"dataAsOf":"2026-07-17T13:30:34.360Z","landed_price_estimate":236889,"import_tax_applied":true,"match_confidence":{"score":0.82,"level":"high"},"cheaper_than_source":true,"savings_cents":13379}],"sources":{"mercadolivre":"ok","shopee":"not_configured","aliexpress":"ok"},"count":1,"data_as_of":"2026-07-20T18:00:00.000Z","disclaimer":"Prices and availability are captured live from each marketplace at the time of the call and change constantly — `dataAsOf` states exactly when. Always confirm on the marketplace before purchasing. Links may be affiliate links."}}}},"402":{"description":"Payment Required (x402). Pay to receive the response."}}}},"/v1/preview/search":{"get":{"operationId":"previewSearch","summary":"Free teaser: 1 result, canonical link only","tags":["Product search"],"security":[],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"example":"iphone"}],"responses":{"200":{"description":"One offer, trimmed."}}}},"/v1/deals":{"get":{"operationId":"dealsFeed","summary":"Free: AliExpress trending / best-seller deals feed","description":"Free trending-deals feed from AliExpress: today's hot / best-seller products, ranked by our affiliate margin, as the same normalized offers as /v1/search (BRL prices in cents, canonical + affiliate links, rating, sold count). Optional keywords (q), category ids, price window and buyer state (uf). AliExpress-only — the one marketplace here with a deals API. Free by decision: the value is the affiliate deal itself, so clicks, not a paywall, are the point.","tags":["Product search"],"security":[],"parameters":[{"name":"q","in":"query","required":false,"description":"Optional keywords to focus the feed. Omit for the broad trending list.","schema":{"type":"string","minLength":2,"description":"Optional keywords to focus the feed. Omit for the broad trending list.","examples":["fone de ouvido"]},"example":"fone de ouvido"},{"name":"category","in":"query","required":false,"description":"Optional comma-separated AliExpress category ids to scope the feed.","schema":{"type":"string","description":"Optional comma-separated AliExpress category ids to scope the feed.","examples":["100003109"]},"example":"100003109"},{"name":"limit","in":"query","required":false,"description":"How many deals to return. Cap 20.","schema":{"type":"integer","minimum":1,"maximum":20,"default":10,"description":"How many deals to return. Cap 20."}},{"name":"sort","in":"query","required":false,"description":"Price ordering. `relevance` keeps the commission ranking.","schema":{"enum":["price_asc","price_desc","relevance"],"default":"price_asc","description":"Price ordering. `relevance` keeps the commission ranking."}},{"name":"min_price","in":"query","required":false,"description":"Minimum price in BRL (e.g. 49.90).","schema":{"type":"number","minimum":0,"description":"Minimum price in BRL (e.g. 49.90)."}},{"name":"max_price","in":"query","required":false,"description":"Maximum price in BRL.","schema":{"type":"number","minimum":0,"description":"Maximum price in BRL."}},{"name":"uf","in":"query","required":false,"description":"Buyer's 2-letter Brazilian state, for the ICMS rate in landed-price estimates.","schema":{"type":"string","description":"Buyer's 2-letter Brazilian state, for the ICMS rate in landed-price estimates.","examples":["SP"]},"example":"SP"}],"responses":{"200":{"description":"Trending AliExpress offers, normalized, with affiliate links.","content":{"application/json":{"schema":{"type":"object"},"example":{"deals":true,"source":"aliexpress","query":"fone de ouvido","results":[{"marketplace":"aliexpress","productId":"1005011820157510","title":"Excellent A8 Wireless Bluetooth Earbuds Active Noise Cancellation","priceCents":8919,"originalPriceCents":20270,"url":"https://www.aliexpress.com/item/1005011820157510.html","affiliateUrl":"https://s.click.aliexpress.com/e/_c2ROmufZ","imageUrl":"https://ae-pic-a1.aliexpress-media.com/kf/S9797cb68d7f54af6a1e0544043443f47J.jpg","seller":{"id":"1105334068","name":"Shop1105334068 Store","officialStore":false},"rating":4.85,"soldCount":84,"dataAsOf":"2026-07-17T13:30:34.360Z"}],"sources":{"aliexpress":"ok"},"count":1,"data_as_of":"2026-07-20T18:00:00.000Z","disclaimer":"Prices and availability are captured live from each marketplace at the time of the call and change constantly — `dataAsOf` states exactly when. Always confirm on the marketplace before purchasing. Links may be affiliate links."}}}},"422":{"description":"Invalid input (free — no payment on this route)."},"503":{"description":"AliExpress not configured on this deployment."}}}},"/v1/taxes/import":{"get":{"operationId":"importTaxCalculator","summary":"Free: estimate the Brazilian import tax (landed price) of a cross-border purchase","description":"Estimate the Brazilian import tax on a cross-border purchase (landed price). Give the product value (and freight) in BRL cents or in USD, plus an optional buyer state (uf); get back the Import Tax (0% up to US$50, else 30% − US$20), the ICMS por-dentro by state, the total landed price, the USD rate used (Bacen PTAX) and the ruleset version. Free, deterministic. MP 1.357/2026 — may change.","tags":["Taxes"],"security":[],"parameters":[{"name":"product_cents","in":"query","required":false,"description":"Product value in BRL cents (e.g. 30000 = R$300).","schema":{"type":"integer","minimum":1,"description":"Product value in BRL cents (e.g. 30000 = R$300).","examples":[30000]},"example":30000},{"name":"freight_cents","in":"query","required":false,"description":"Freight in BRL cents (part of the customs base).","schema":{"type":"integer","minimum":0,"description":"Freight in BRL cents (part of the customs base)."}},{"name":"insurance_cents","in":"query","required":false,"description":"Insurance in BRL cents, if any.","schema":{"type":"integer","minimum":0,"description":"Insurance in BRL cents, if any."}},{"name":"product_usd","in":"query","required":false,"description":"Alternative: product value in USD (e.g. 59.90).","schema":{"type":"number","minimum":0,"description":"Alternative: product value in USD (e.g. 59.90)."}},{"name":"freight_usd","in":"query","required":false,"description":"Alternative: freight in USD.","schema":{"type":"number","minimum":0,"description":"Alternative: freight in USD."}},{"name":"insurance_usd","in":"query","required":false,"description":"Alternative: insurance in USD.","schema":{"type":"number","minimum":0,"description":"Alternative: insurance in USD."}},{"name":"uf","in":"query","required":false,"description":"Buyer's 2-letter Brazilian state, for the ICMS rate. Default: 20% (the ceiling).","schema":{"type":"string","description":"Buyer's 2-letter Brazilian state, for the ICMS rate. Default: 20% (the ceiling).","examples":["SP"]},"example":"SP"}],"responses":{"200":{"description":"Tax breakdown, landed price, USD rate used and ruleset version.","content":{"application/json":{"schema":{"type":"object"},"example":{"input":{"currency":"BRL","product_cents":30000,"freight_cents":5000,"insurance_cents":0,"uf":"SP"},"breakdown":{"band":"taxed","customs_value_cents":35000,"usd_value":64.46,"ii_cents":0,"icms_rate":0.17,"icms_cents":7169,"total_tax_cents":7169,"landed_price_cents":42169},"usd_rate_used":{"rate":5.43,"quote_date":"2026-07-16","source":"Bacen PTAX (venda)"},"assumptions":{"uf":"SP","icms_rate":0.17,"icms_rate_defaulted":false,"freight_included":true,"rules_version":"mp-1357-2026-05-12","data_as_of":"2026-07-17"},"partial":false,"rules_version":"mp-1357-2026-05-12","data_as_of":"2026-07-17","disclaimer":"Estimate only. The marketplace checkout (Remessa Conforme) is the source of truth and collects the actual tax. Rules are versioned (MP 1.357/2026, in force since 12/05/2026) and may change — the MP lapses if Congress does not convert it within 120 days (~sep/2026). `rules_version`/`data_as_of` say which ruleset produced this. Freight and insurance are part of the customs base; a missing freight makes the estimate a lower bound (`partial`)."}}}},"422":{"description":"Invalid input (free — no payment on this route)."}}}},"/health":{"get":{"operationId":"health","summary":"Health check","security":[],"responses":{"200":{"description":"OK"}}}}}}