Guia

Buybox

A leitura mais recente da buybox de um produto de marketplace: quem vence e a lista completa de sellers, na ordem em que o site serviu. Um produto por GET, ou um lote de até 200 referências por POST - mesmo dado, mesma cobrança por item.

Um produto

GET /v1/{marketplace}/products/{catalog_id}/buybox

{catalog_id} é o id de catálogo do marketplace (MLB1234567890) ou o SKU que já monitoramos para você.

Query paramDescrição
include_sellersbool (default true). false devolve só vencedor + seller_count - payload menor, mesmo preço.
Request
curl https://api.geth.app/v1/mercado-livre/products/MLB1234567890/buybox \
  -H "Authorization: Bearer gk_live_SEU_TOKEN"
Response
{
  "item": "MLB1234567890",
  "status": "FOUND",
  "billable": true,
  "catalog_id": "MLB1234567890",
  "product_name": "Produto X",
  "product_url": "https://.../p/MLB1234567890",
  "seller_count": 32,
  "winner": {
    "rank": 1, "seller_id": 9001, "external_seller_id": "1234567",
    "seller_name": "Loja Y", "is_official": false, "price": 199.90, "stock": true
  },
  "sellers": [ { "rank": 1, ... } ],
  "scan": 4,
  "read_at": "2026-07-29T10:00:00-03:00",
  "request_id": "0f5a...-...-..."
}

É o mesmo objeto que vem dentro de results no lote, mais o request_id daquela tentativa. Os contadores attempted/billable de lote não aparecem aqui: é uma tentativa só, e o campo billable do próprio item diz se ela é cobrada.

Um lote

POST /v1/{marketplace}/products/buybox
Request
curl -X POST https://api.geth.app/v1/mercado-livre/products/buybox \
  -H "Authorization: Bearer gk_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "items": ["MLB1234567890", "MLB9876543210"], "include_sellers": true }'
CampoTipoDescrição
itemslista de string (1..200)Referências a tentar: id de catálogo do marketplace (MLB...) ou SKU que já monitoramos.
include_sellersbool (default true) false devolve só vencedor + seller_count.

Referência repetida no mesmo request conta 1 tentativa (dedup por request): um retry interno do seu lado, dentro do mesmo lote, não é cobrado duas vezes. Requests separados são tentativas separadas, mesmo com o mesmo item.

Response
{
  "request_id": "0f5a...-...-...",
  "attempted": 2,
  "billable": 2,
  "results": [
    { "item": "MLB1234567890", "status": "FOUND", "billable": true, ... },
    { "item": "MLB9876543210", "status": "EMPTY", "billable": true,
      "reason": "no buybox reading for this item" }
  ]
}

attempted, billable e request_id são os campos de reconciliação da fatura - guarde-os. O detalhe está em Uso e faturamento.

status por item

StatusSignificadoCobrado?
FOUNDTinha buybox; vem a lista de sellers da leitura mais recente.sim
EMPTYItem tentado e sem buybox, ou não monitorado (veja reason).sim (termo do contrato)
ERRORFalha nossa na tentativa.não

Item sem buybox não é 404: é 200 com status: EMPTY, e é cobrado - a tentativa aconteceu. Só o marketplace desconhecido responde 404, e aí nada é cobrado.

Ordem dos sellers

sellers vem na ordem em que o marketplace serviu, e rank: 1 é o vencedor da buybox - que não é necessariamente o mais barato (no estudo Docol, o mais barato venceu em 81% dos casos). A API nunca reordena por preço.

Frescor do dado

read_at é quando aquela leitura foi coletada, não quando você pediu. A frequência e a cobertura da coleta são acordadas no contrato; use read_at para saber exatamente a idade do dado que recebeu.

Região

Filtro por região/CEP ainda não existe. Quando existir, será query param (?postal_code=...), nunca rota. Hoje um param desconhecido é ignorado sem erro - mandar cedo não quebra nada, mas também não filtra nada.