API da geth

Visão geral

A API da geth entrega a leitura mais recente do buybox de marketplace: quem vence, a que preço, e a lista completa de sellers - como um comprador de verdade vê. Você consulta um produto ou um lote de até 200, e acompanha seu próprio consumo pelo medidor.

Base URL e formato

https://api.geth.app

Caminhos versionados em /v1. Mudança incompatível vira /v2, nunca uma edição silenciosa do contrato.
Requisições e respostas em JSON. Datas em ISO 8601 com offset (2026-07-29T10:00:00-03:00).
Toda chamada é autenticada por Secret key (gk_live_...).

Endpoints

O primeiro segmento depois de /v1 é o marketplace (mercado-livre, ...), e depois vem o recurso e o aspecto que você quer dele:

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

POST /v1/{marketplace}/products/buybox

GET /v1/usage

Os dois primeiros devolvem o mesmo dado - a buybox - em dois modos de consumo: um produto (GET) ou um lote de até 200 referências (POST). O terceiro é o seu medidor de consumo. O detalhe de cada um está no guia do buybox e na API Reference.

Alguns caminhos já estão declarados para a fase 2 e hoje respondem 501: o produto em si (/v1/{marketplace}/products/{catalog_id}), o catálogo de um seller e o namespace de configuração da coleta (/v1/scans/..., /v1/lists/...). Os nomes scans, lists, usage, keys, admin e delivery são reservados: nunca serão marketplace.

Comece em três passos

1. Receba sua Secret key

A chave é emitida pela nossa equipe no onboarding e entregue por canal seguro. Ela não expira - é revogada e reemitida. Detalhes em Autenticação.

2. Leia a buybox de um produto

Request

# {catalog_id} é o id de catálogo do marketplace (MLB...) ou um SKU que já monitoramos
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,
  "product_name": "Produto X",
  "seller_count": 32,
  "winner": { "rank": 1, "seller_name": "Loja Y", "price": 199.90, "stock": true },
  "sellers": [ /* a lista completa, na ordem em que o site serviu */ ],
  "read_at": "2026-07-29T10:00:00-03:00",
  "request_id": "0f5a..."
}

3. Escale para o lote

Sortimento inteiro se consulta em lote: até 200 referências por request, mesmo preço por item, e uma fração do rate limit que 200 GETs gastariam. Veja o guia do buybox.

Como a cobrança funciona

Cada item pedido é uma tentativa, e cada tentativa é cobrada - inclusive quando o item não tem buybox (status: EMPTY, termo do contrato). A API devolve e armazena contagem; o preço unitário está no seu contrato e a fatura aplica. Falha nossa (ERROR, 503) nunca é cobrada. O guia de uso e faturamento mostra como conferir a fatura linha a linha.

PróximoAutenticação →