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 (mercadolivre, ...), e depois vem o recurso e o aspecto que você quer dele:

O slug do marketplace é normalizado: maiúsculas e separadores (o hífen, por exemplo) são ignorados, então uma URL escrita em CamelCase ou com hífen chega na mesma loja. A forma canônica, que é a que volta no dado e a que esta doc usa, é tudo junto e em minúsculas: mercadolivre.

POST /v1/catalog/items

GET /v1/catalog/items

GET /v1/catalog/report

GET /v1/reads

GET /v1/reads/{read_id}/items

GET /v1/{store}/products/{catalog_id}

GET /v1/{store}/products/{catalog_id}/history

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

POST /v1/{marketplace}/products/buybox

GET /v1/usage

A sua lista é a entrada: os itens que você quer monitorar, enviados por você - pelo console ou por POST /v1/catalog/items, dizendo se aquele envio é adição ou a lista inteira. Enviar a lista não é cobrado.

As leituras são o jeito de consumir lote agendado: você lista o que rodou, acompanha o que está rodando e drena os itens com cursor retomável, no vocabulário schema.org Product+Offer. A consulta pontual e o histórico respondem por item - {store} aceita o slug ou o id numérico. A buybox segue com seus dois modos (um produto, ou lote de até 200). E /v1/usage é o seu medidor: da chave, não de uma loja - ele soma tudo que ela consumiu, em qualquer endpoint. Tudo na API Reference.

Alguns caminhos já estão declarados para a fase 2 e hoje respondem 501: 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, delivery, catalog e reads são reservados: nunca serão marketplace.

Comece em três passos

1. Receba sua Secret key e mande sua lista

A primeira chave é emitida pela nossa equipe no onboarding e entregue por canal seguro; daí em diante você cria as suas no console. Ela não expira - é revogada e reemitida. Detalhes em Autenticação. Com a chave na mão, mande a sua lista (planilha no console ou POST /v1/catalog/items).

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/mercadolivre/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 →