Documentação da API

Introdução

A API do GameMarket permite que vendedores verificados integrem suas aplicações com a plataforma. Com ela, você pode:

• Criar novos anúncios automaticamente (limite: 50/dia por conta)
• Gerenciar seus produtos (listar, atualizar, ativar/desativar)
• Consultar pedidos e histórico de vendas
• Verificar saldo e estatísticas
• Listar jogos disponíveis na plataforma

Nota: Para usar a API, você precisa ser um vendedor verificado. Acesse suas configurações para solicitar verificação.

Autenticação

A API utiliza chaves de API para autenticação. Você pode criar e gerenciar suas chaves na página de configurações.

Usando a chave de API

Inclua sua chave de API no header x-api-key de todas as requisições:

Exemplo de requisição (também aceita /api/gamemarket/...)

Permissões

Cada chave de API pode ter diferentes permissões:

• read Permite leitura de dados (produtos, pedidos, saldo)
• write Permite criação e atualização de recursos
• delete Permite exclusão de recursos

Gestão de Chaves

Endpoints para gerenciar suas chaves de API. Estes endpoints requerem autenticação por sessão (login no site).

POST /api/api-keys

Cria uma nova chave de API. Você pode ter no máximo 5 chaves ativas.

Headers

• Content-Type: application/json - Tipo do conteúdo

GET /api/api-keys

Lista todas as suas chaves de API.

DELETE /api/api-keys/:id

Revoga uma chave de API. A chave não poderá mais ser usada.

Parâmetros de Path

• id (number) obrigatório - ID da chave de API

GET /api/api-keys/:id/usage

Retorna o histórico de uso de uma chave de API (últimas 100 requisições).

Parâmetros de Path

• id (number) obrigatório - ID da chave de API

Produtos

Endpoints para gerenciar seus produtos na plataforma.

GET /api/v1/products

read

Lista todos os seus produtos com paginação. Retorna um campo 'status' calculado para cada produto.

Query Parameters

• page (number) default: 1 - Número da página
• limit (number) default: 20 - Itens por página (máx 100)
• status (string) - Filtrar por status: 'ativo' (aprovado e visível), 'desativado' (inativo manualmente), 'em_analise' (aguardando aprovação), 'rejeitado' (negado pela equipe), 'todos' (sem filtro)

Headers

• x-api-key: gm_sk_... - Sua chave de API

GET /api/v1/products/:id

read

Retorna os detalhes de um produto específico.

Parâmetros de Path

• id (number) obrigatório - ID do produto

Headers

• x-api-key: gm_sk_... - Sua chave de API

Nota: Em anúncios com variantes (listingType 'multiple'), o campo variants traz o título, o preço e o estoque de cada variante, e multipleProducts vem sempre null. A resposta do PATCH segue a mesma forma.

POST /api/v1/products

write

Cria um novo anúncio/produto na plataforma. O anúncio ficará pendente de aprovação. Limite: 50 anúncios por dia por conta.

Headers

• x-api-key: gm_sk_... - Sua chave de API
• Content-Type: application/json - Tipo do conteúdo

Corpo da Requisição (JSON)

• title (string) obrigatório - Título do anúncio (5-200 caracteres)
• description (string) obrigatório - Descrição detalhada (20-5000 caracteres)
• price (number) obrigatório - Preço em centavos (mín: 100 = R$ 1,00, ou o mínimo global configurado na categoria)
• game (string) obrigatório - Slug do jogo (use GET /games para listar)
• category (string) default: account - Categoria: 'account' ou 'item'
• warrantyPeriod (number) obrigatório - Período de garantia em dias (valores aceitos: 7, 14 ou 30)
• accountProvenance (string) obrigatório - Procedência: 'creator' (criador original) ou 'resale' (revenda)
• listingType (string) default: single - Tipo de listagem: 'single' ou 'multiple'
• isAutoDelivery (boolean) default: false - Se é entrega automática (⚠️ APENAS para listingType='single')
• autoDeliveryContent (string) - ⚠️ OBRIGATÓRIO se isAutoDelivery=true E listingType='single'. Conteúdo entregue automaticamente (máx 10.000 chars)
• deliveryTime (string) - Prazo de entrega (ex: '1d', '2h', '15min', máx 20 chars)
• imageUrls (string[]) - Array de URLs HTTPS de imagens (máx 10, apenas URLs públicas)

⚠️ Campos Obrigatórios Condicionalmente:

• autoDeliveryContent é obrigatório se isAutoDelivery=true (⚠️ Auto-delivery funciona APENAS com listingType='single')
• imageUrls devem ser HTTPS e acessíveis publicamente (validação automática)
• warrantyPeriod aceita apenas os valores: 7, 14 ou 30 dias

PATCH /api/v1/products/:id

write

Atualiza informações de um produto. Para desativar um anúncio, use isActive: false.

Parâmetros de Path

• id (number) obrigatório - ID do produto

Headers

• x-api-key: gm_sk_... - Sua chave de API
• Content-Type: application/json - Tipo do conteúdo

Corpo da Requisição (JSON)

• title (string) - Novo título (mín: 5 chars, máx: 200) ⚠️ Requer nova aprovação
• description (string) - Nova descrição (mín: 20 chars, máx: 5.000) ⚠️ Requer nova aprovação
• price (number) - Novo preço em centavos (mín: 100 = R$ 1,00, ou o mínimo global configurado na categoria)
• isActive (boolean) - Ativar (true) ou desativar (false) o anúncio
• warrantyPeriod (number) - Período de garantia em dias (valores aceitos: 7, 14 ou 30)
• deliveryTime (string) - Prazo de entrega (máx 20 chars, ex: '1d', '2h')
• autoDeliveryContent (string) - Conteúdo de entrega automática (máx 10.000 chars)

⚠️ Importante sobre edições (PATCH):

• Alterações em title ou description retornam o produto para status "em_analise" (nova aprovação necessária)
• Produtos com status "rejeitado" não podem ser editados via API (HTTP 403)
• Para desativar um anúncio temporariamente, use isActive: false
• Voltam para análise as alterações reais de title, description, warrantyPeriod e deliveryTime. Enviar um valor igual ao atual não conta como alteração e não reenvia o anúncio para análise.
• warrantyPeriod só vale para anúncios da categoria account; nos demais, o campo é ignorado.
• Reativar (isActive: true) exige anúncio aprovado, com estoque e fora do Modo Offline. Os códigos de recusa estão na seção de códigos de erro.

Nota: Por segurança, a exclusão de produtos via API foi desabilitada. Para desativar um anúncio, use PATCH /api/v1/products/:id com isActive: false. Para excluir permanentemente, acesse o painel do vendedor no site.

Saldo

GET /api/v1/balance

read

Retorna o saldo atual do vendedor.

Headers

• x-api-key: gm_sk_... - Sua chave de API

Pedidos

GET /api/v1/orders

read

Lista todos os seus pedidos (vendas e compras).

Query Parameters

• page (number) default: 1 - Número da página
• limit (number) default: 20 - Itens por página (máx 100)
• type (string) - Filtrar por tipo (sales, purchases)
• status (string) - Filtrar por status

Headers

• x-api-key: gm_sk_... - Sua chave de API

GET /api/v1/orders/:id

read

Retorna os detalhes de um pedido. Aceita orderCode (ex: GM-AB12CD) ou ID numérico como parâmetro.

Parâmetros de Path

• id (string) obrigatório - OrderCode (ex: GM-AB12CD) ou ID numérico do pedido

Headers

• x-api-key: gm_sk_... - Sua chave de API

Estatísticas

GET /api/v1/stats

read

Retorna estatísticas gerais do vendedor.

Headers

• x-api-key: gm_sk_... - Sua chave de API

Jogos

GET /api/v1/games

read

Lista todos os jogos disponíveis e ativos na plataforma. Use o campo slug ao criar produtos.

Headers

• x-api-key: gm_sk_... - Sua chave de API

Limites & Quotas

Rate Limits

• Requisições por minuto: 30/min
• Requisições por dia: 3000/dia

💡 Os limites são por conta (não por chave). Todas as suas chaves compartilham o mesmo rate limit. Headers de resposta incluem: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (timestamp Unix em segundos)

Limites de Criação

• Anúncios por dia (via API): 50/dia por conta
• Imagens por anúncio: Máx 10
• Conteúdo auto-delivery: Máx 10,000 chars

Limites de Tamanho

• Título do produto: 5-200 chars
• Descrição: 20-5,000 chars
• Preço mínimo: R$ 1,00 (padrão; configurável por jogo)
• Preço máximo: R$ 1.000.000,00 por anúncio

Melhores Práticas

Segurança

• Nunca exponha sua API key no código client-side
  Use variáveis de ambiente e sempre faça chamadas pelo backend
• Rotacione suas chaves periodicamente
  Recomendamos rotação a cada 90 dias por segurança
• Monitore o uso das suas chaves
  Verifique regularmente os logs de acesso em Configurações → API

Performance

• Implemente cache local
  Liste de jogos (GET /games) raramente muda - cache por 24h
• Use paginação eficientemente
  Limite máximo é 100 itens. Use limit menor para respostas mais rápidas
• Implemente retry com backoff exponencial
  Em caso de erro 429 (rate limit), aguarde o tempo indicado em X-RateLimit-Reset

Validação de Dados

• Valide antes de enviar
  Verifique tipos, limites e formatos localmente antes de fazer requisições
• Sempre verifique o campo success
  Respostas incluem "success": true/false, nunca assuma sucesso sem verificar
• Produtos editados podem requerer nova aprovação
  Alterações reais em título, descrição, garantia (warrantyPeriod) ou prazo de entrega (deliveryTime) retornam o produto para status "em_analise"

Códigos de Erro

401 API key inválida ou ausente

A chave de API não foi fornecida ou está incorreta.

403 Permissão insuficiente

A chave de API não tem permissão para esta operação.

403 Vendedor em débito (SELLER_IN_DEBT)

A API foi suspensa porque o vendedor possui débito pendente com a plataforma. Regularize as disputas para restaurar o acesso.

429 Rate limit excedido

Você excedeu o limite de requisições. Aguarde antes de tentar novamente.

404 Recurso não encontrado

O recurso solicitado não existe ou você não tem acesso a ele.

500 Erro interno do servidor

Ocorreu um erro inesperado. Tente novamente mais tarde.

403 - Conta de vendedor restrita (SELLER_RESTRICTED)

A API fica suspensa enquanto a conta estiver restrita. Fale com o suporte.

Rotas: Todas as rotas

400 - Preço acima do máximo por anúncio

O preço aceita no máximo 100000000 centavos (R$ 1.000.000,00). Acima disso, a requisição é recusada com erro de validação (error "Validation error") no campo price. Confira se o valor está em centavos e não foi multiplicado por 100 duas vezes.

Rotas: POST /api/v1/products · PATCH /api/v1/products/:id

409 - Estoque em uso (STOCK_BUSY)

A troca de credenciais (autoDeliveryContent) coincidiu com uma venda ou outra alteração de estoque em andamento. Nada foi alterado e a resposta traz retryable: true: reenvie a mesma requisição em alguns segundos.

Rotas: PATCH /api/v1/products/:id

410 - Anúncio removido em definitivo (LISTING_TAKEN_DOWN)

Recusa ao reativar (isActive: true). O anúncio foi removido pela moderação e não pode ser reativado nem editado. Se você acredita que houve um engano, fale com o suporte.

Rotas: PATCH /api/v1/products/:id

410 - Anúncio recusado em definitivo (LISTING_PERMANENTLY_REJECTED)

Recusa ao reativar (isActive: true). O anúncio foi recusado em definitivo pela moderação e não pode ser reativado, editado nem reenviado para análise. Se você acredita que houve um engano, fale com o suporte.

Rotas: PATCH /api/v1/products/:id

409 - Pausado pelo Modo Offline (OFFLINE_PAUSED)

Recusa ao reativar (isActive: true). Desative o Modo Offline no painel do vendedor: isso reativa de uma vez todos os anúncios pausados por ele.

Rotas: PATCH /api/v1/products/:id

400 - Anúncio não aprovado (NOT_APPROVED)

Recusa ao reativar (isActive: true). Só anúncio aprovado pode ser ativado: aguarde a análise e ative depois da aprovação.

Rotas: PATCH /api/v1/products/:id

400 - Anúncio sem estoque (NO_STOCK)

Recusa ao reativar (isActive: true). Reponha o estoque antes de ativar. Em listagem única com entrega automática, as novas credenciais podem ir em autoDeliveryContent na mesma requisição do isActive: true; nos demais casos, use o painel do vendedor.

Rotas: PATCH /api/v1/products/:id

200 - Nenhuma alteração aplicada

Quando todos os campos enviados entre title, description, warrantyPeriod, deliveryTime e isActive já tinham o valor atual e nenhum outro campo foi enviado, a resposta é 200 com a mensagem "No changes applied": nada é gravado e o anúncio não volta para análise. Um corpo sem nenhum campo aplicável ao anúncio continua respondendo 400 ("No applicable fields").

Rotas: PATCH /api/v1/products/:id

Exemplos de Código

• cURL
• JavaScript
• Python
• PHP
• Ruby
• Go
• C#

Listar produtos

Atualizar produto

Consultar saldo