Pronta para conectar.

Sua primeira consulta

Use a URL base https://api.meuretro.com.br e uma chave de cliente com acesso ativo. Os exemplos abaixo leem a variável de ambiente GAMEPRICEAPI_KEY no seu servidor.

curl --fail-with-body --get \
  'https://api.meuretro.com.br/v1/products' \
  --header "Authorization: Bearer $GAMEPRICEAPI_KEY" \
  --data-urlencode 'q=mario' \
  --data-urlencode 'limit=5'

// Execute no backend. Node.js 20+.
const key = process.env.GAMEPRICEAPI_KEY;
if (!key) throw new Error('Configure GAMEPRICEAPI_KEY');

const url = new URL('https://api.meuretro.com.br/v1/products');
url.search = new URLSearchParams({ q: 'mario', limit: '5' });
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${key}` },
  signal: AbortSignal.timeout(10000)
});
const body = await response.json();
if (!response.ok) {
  throw new Error(`${response.status}: ${body.error?.code}`);
}
console.log(body.data);

# Execute no backend. Python 3, biblioteca padrão.
import json
import os
from urllib.parse import urlencode
from urllib.request import Request, urlopen
from urllib.error import HTTPError

query = urlencode({"q": "mario", "limit": 5})
request = Request(
    "https://api.meuretro.com.br/v1/products?" + query,
    headers={"Authorization": "Bearer " + os.environ["GAMEPRICEAPI_KEY"]}
)
try:
    with urlopen(request, timeout=10) as response:
        print(json.load(response)["data"])
except HTTPError as error:
    print(error.code, json.load(error)["error"]["code"])

O exemplo cURL usa um shell compatível com bash. Configure a variável de ambiente fora do código e mantenha a chave em segredo.

Autenticação e acesso comercial

Envie a chave exclusivamente no cabeçalho Authorization, com o esquema Bearer. Todos os endpoints de /v1/, incluindo imagens, cobertura e consumo, exigem autenticação e acesso ativo.

Authorization: Bearer SUA_CHAVE

A equipe emite a chave e ativa o acesso após confirmar as condições comerciais. Uma chave emitida para uma conta pendente, suspensa ou expirada não libera os dados. A página pública não oferece cadastro automático ou checkout.

• Mantenha a chave no backend, em uma variável de ambiente ou gerenciador de segredos.
• Não inclua a chave em URLs, aplicativos cliente, JavaScript público, repositórios ou logs.
• Não use a chave diretamente em uma tag de imagem. Seu backend deve buscar o arquivo autenticado.
• Em caso de exposição, solicite a revogação e a emissão de uma nova chave pelo canal de atendimento.

Uso interno ou em um app?

A diferença principal é quem terá acesso às referências no seu produto — não se o seu app é pago ou gratuito. Escolha a modalidade pelo uso e dimensione a cota pelo volume de requisições feitas pelo seu backend.

As cotas-base orientam novas contratações. A ativação é manual, após o acordo comercial; não há contratação automática, acesso ilimitado nem cobrança automática de excedentes. Consulte os limites efetivos da sua conta em /v1/usage.

O que precisa constar do acordo

• Projetos, marcas, ambientes e formas de exibição autorizados, além da cobertura de dados necessária.
• Uso de imagens, créditos e atribuições aplicáveis. Ter acesso ao arquivo não substitui as permissões de uso.
• Política de cache, retenção e tratamento dos dados após o encerramento do contrato.
• Quotas, validade do acesso e eventuais ajustes de capacidade; volumes maiores dependem de análise técnica.

Uma integração para muitos usuários

O navegador ou celular do seu usuário conversa com o seu backend. Seu backend consulta a GAMEPRICEAPI com uma chave secreta, atualiza o cache permitido no contrato e entrega a experiência do app. Não distribua a chave aos usuários nem crie um proxy público irrestrito da API.

1. Encontre os produtos e salve os IDs canônicos, como gameprice:12345.
2. Atualize os IDs conhecidos em lotes de até 100, com uma fila e frequência compatíveis com a sua cota e a atualização dos dados.
3. Sirva as referências do seu cache, preservando as datas de observação e sinalizando valores antigos conforme stale.
4. Busque imagens separadamente apenas quando necessário e mantenha os créditos e a política de cache contratados.

O cache reduz chamadas repetidas, mas não autoriza revenda ou distribuição da base. Combine a frequência de atualização com a cobertura disponível; consultas de clientes não provocam uma nova coleta no fornecedor.

O modelo de produto

O ID público usa o namespace gameprice, como gameprice:12345. Trate o ID completo como uma chave opaca: utilize o valor retornado pela API, sem calcular IDs nem deduzir equivalências com outros catálogos. Identificadores complementares ficam em metadata.identifiers. Plataforma, país e tipo de lançamento ajudam a distinguir regiões e edições.

As respostas usam o formato canônico gameprice:, inclusive nos IDs ausentes, nos links de imagens e em next_after.

{
  "id": "gameprice:12345",
  "title": "Jogo de exemplo",
  "identifiers": { "gamepriceapi": "12345" },
  "platform_id": 6,
  "country_id": 1,
  "release_type": 0,
  "category_id": 0,
  "product_type": "game",
  "currency": "USD",
  "metadata": {
    "title": "Jogo de exemplo",
    "description": null,
    "release_date": null,
    "developers": [],
    "publishers": [],
    "genres": [{ "id": null, "name": "Aventura" }],
    "players": null,
    "platform": { "id": 6, "name": null },
    "country": { "id": 1, "name": null },
    "edition": null,
    "identifiers": { "gamepriceapi": "12345" },
    "barcodes": [],
    "images": [],
    "links": [],
    "attributes": {}
  },
  "metadata_observed_at": "2026-10-11T12:00:00.000Z",
  "prices": {
    "loose": {
      "amount_cents": 2500,
      "observed_at": "2026-10-11T12:00:00.000Z",
      "stale": false
    },
    "cib": {
      "amount_cents": 4500,
      "observed_at": "2026-10-11T12:00:00.000Z",
      "stale": false
    },
    "new": {
      "amount_cents": null,
      "observed_at": null,
      "stale": true
    }
  },
  "provenance": {
    "source": "EBAY",
    "delivered_by": "GAMEPRICEAPI",
    "source_role": "upstream_marketplace",
    "acquisition_method": "licensed_partner_reference",
    "source_basis": "partner_reported",
    "source_url": null,
    "provider_as_of": null,
    "fetched_at": "2026-10-11T12:00:00.000Z",
    "match_type": "exact_provider_identity"
  }
}

Identidade e metadados

Preços que mantêm o contexto

A GAMEPRICEAPI entrega referências processadas recebidas por uma integração licenciada. O parceiro informa o eBay como mercado de origem; isso é diferente de consultar diretamente a API do eBay. currency é sempre USD; amount_cents é um inteiro em centavos. Por exemplo, 12345 representa US$ 123,45.

Como interpretar a origem

O serviço não representa afiliação oficial com o eBay e não entrega uma lista de transações ou vendas concluídas. Links em metadata.links ajudam a localizar produtos; não são evidência de cálculo dos preços.

Quando uma atualização não traz um preço válido, a API preserva o último valor conhecido e a sua data de observação original. Use stale junto das datas para decidir como exibir referências antigas.

Referência dos endpoints

Todas as rotas abaixo exigem Authorization: Bearer SUA_CHAVE e acesso ativo. Respostas de dados usam JSON, exceto o download de imagens.

{
  "data": [],
  "next_after": null
}

Com resultados, data contém objetos de produto. Filtros não reconhecidos ou repetidos retornam 400 invalid_query.

{
  "ids": ["gameprice:12345", "gameprice:67890"]
}

A resposta tem data com os produtos encontrados e not_found com os IDs ausentes. IDs repetidos, formato inválido, lista vazia ou mais de 100 IDs retornam 400 invalid_product_ids. O corpo deve ter apenas a propriedade ids.

Imagens com acesso protegido

metadata.images lista somente as imagens já armazenadas no cache da API. Use a url relativa retornada, resolvida na URL base, e envie o mesmo cabeçalho Bearer usado nas consultas JSON.

curl --fail-with-body \
  'https://api.meuretro.com.br/v1/products/gameprice:12345/image?variant=cover' \
  --header "Authorization: Bearer $GAMEPRICEAPI_KEY" \
  --output cover.img

A resposta de sucesso é binária, com o tipo de arquivo em Content-Type. variant=cover solicita a capa; outras variantes só devem ser utilizadas quando aparecerem em metadata.images. A presença de uma imagem não implica que outras vistas estejam disponíveis.

Para exibir imagens no seu produto, faça a busca a partir do backend e entregue o conteúdo conforme as condições do seu contrato. Uma tag <img> apontando diretamente para a API não envia o cabeçalho Bearer.

Catálogos e plataformas

Retorna {"data": [...]} com os catálogos configurados e sua cobertura atual. Cada entrada contém id, platform_id, country_id, release_type, products, priced_products, with_barcodes, with_images, last_success_at e next_run_at.

last_success_at indica a última sincronização bem-sucedida do catálogo. next_run_at é uma referência operacional de agendamento, não uma garantia de conclusão ou disponibilidade de novos dados.

Retorna {"data": [...]} com id, name e products por plataforma. O nome pode ser null quando indisponível na fonte.

Consumo da sua conta

Consulte os contadores da sua própria conta no mês corrente em UTC. A resposta inclui esta requisição e contém:

Os contadores ajudam no planejamento da integração. Não representam uma fatura e não substituem as condições comerciais contratadas.

Paginação e sincronização

Para percorrer resultados, repita a busca com os mesmos filtros e envie o valor de next_after no parâmetro after. Encerre quando next_after for null. O cursor usa a ordenação por ID; não calcule o próximo ID manualmente.

1. Faça a primeira consulta com os filtros desejados e limit.
2. Processe data e armazene os produtos pelo ID completo.
3. Se houver next_after, consulte a próxima página preservando os filtros.

updated_after inclui registros cujo fetched_at ou metadata_observed_at é posterior ao instante informado. Uma página vazia indica ausência de correspondências naquele momento.

A API atual oferece consulta JSON paginada e em lote. Não há download CSV, exportação integral em um único arquivo, endpoint de histórico de preços ou de vendas individuais concluídas. Paginar o catálogo para um cache autorizado não amplia o direito de redistribuí-lo.

Limites e cotas

Os limites efetivos são definidos por conta e compartilhados entre suas chaves. Criar ou alternar chaves não multiplica a cota. As modalidades-base têm 60 requisições por minuto; Uso interno inclui 10.000 por mês e Apps e sites, 100.000. Ajustes dependem do acordo comercial e da capacidade aprovada.

Cada requisição autenticada admitida em /v1/ consome uma consulta, inclusive erros de parâmetros e produtos não encontrados. Um lote de até 100 IDs consome uma consulta; cada página de resultados e cada download de imagem são requisições separadas. Itens retornados são contabilizados à parte e não substituem a unidade de cota.

A cota mensal segue o mês de calendário em UTC, não 30 dias corridos nem a data de contratação. Ao atingir a cota de conta, a API retorna 429 com Retry-After; requisições recusadas por esse limite não acrescentam consumo. Não há cobrança automática de excedentes. A rota /v1/usage também consome uma consulta e fica indisponível quando a conta está limitada: acompanhe os saldos antes de esgotá-los.

Os cabeçalhos de saldo são enviados em requisições admitidas. Rejeições anteriores à reserva podem não conter os saldos. Uma rejeição da proteção de entrada pode ter corpo não JSON e não incluir Retry-After; nesse caso, use espera progressiva com variação aleatória e um limite de tentativas.

Erros e retentativas

Erros gerados pela aplicação usam um objeto error com código estável e identificador da requisição. Guarde o request_id para suporte e evite registrar o cabeçalho de autenticação. A camada de proteção de entrada pode responder sem JSON ou identificador; verifique o status e o tipo de conteúdo antes de interpretar o corpo.

{
  "error": {
    "code": "invalid_api_key",
    "request_id": "00000000-0000-4000-8000-000000000000"
  }
}

As operações documentadas são de leitura, incluindo as consultas em lote via POST. Repetir uma requisição admitida consome outra consulta; evite retentativas automáticas de erros 400, 401 e 403.

Disponibilidade do serviço

Endpoint público de disponibilidade básica do processo. Não exige chave e não expõe o catálogo, clientes ou estatísticas do acervo. Uma resposta 200 não atesta a atualização dos preços ou a disponibilidade do fornecedor.

Para avaliar seus dados, use as datas de observação e os sinais de atualização retornados nas consultas autenticadas.