Documentação da API v2 (Beta) - GameMarket

Documentação da API v2 da GameMarket para vendedores e integradores. Procurando a versão estável? Veja a documentação da API v1.

Visão geral

A API v2 mantém a v1 intacta e adiciona: variantes com preço individual, edição de preço e estoque de cada variante, reabastecimento de estoque de entrega automática, criação de anúncios multi-variante, edição em massa de preço e status, mediações, avaliações recebidas, contestação de avaliação e perguntas dos anúncios (ler e responder), com scopes granulares e idempotência obrigatória nas escritas.

Base URL: https://gamemarket.com.br/api/v2 · Autenticação: header x-api-key com chave de prefixo gm_v2_sk_ (chaves v1 e v2 são isoladas entre si).

Autenticação e Scopes

Cada chave v2 recebe scopes granulares na criação (ex.: catalog:read, products:read, products:write, orders:read, mediations:read, reviews:read, reviews:contest, questions:read, questions:write, wallet:read). Endpoint sem o scope necessário responde 403.

Idempotência (obrigatória em escritas)

Toda requisição POST/PATCH exige o header Idempotency-Key (16–255 caracteres [A-Za-z0-9_-]). Reenvios com a mesma chave retornam a mesma resposta sem duplicar a operação.

Sem o header em escrita → 400 (IDEMPOTENCY_KEY_REQUIRED)
Header fora do formato aceito → 400 (IDEMPOTENCY_KEY_INVALID)
Requisição idêntica ainda em processamento → 409 (IDEMPOTENCY_IN_FLIGHT). Aguarde e reenvie com a mesma chave. Não gere uma chave nova: o resultado da primeira requisição ainda não é conhecido.
Chave já usada por outra conta → 409 (IDEMPOTENCY_KEY_CONFLICT). Gere uma chave única para cada operação, por exemplo um UUID v4.
Mesma chave reutilizada com outro método, rota, recurso ou corpo → 422 (IDEMPOTENCY_KEY_REUSED). Nada é executado. Gere uma chave nova para cada operação. A ordem dos campos do JSON não conta como corpo diferente.
Idempotência temporariamente indisponível → 503 (IDEMPOTENCY_UNAVAILABLE). Nada foi executado. Aguarde os segundos do header Retry-After e reenvie com a mesma chave.
Reenvio após sucesso → resposta original armazenada (janela de 24h)
Reenvio da mesma requisição após um erro → o mesmo erro armazenado (janela de 24h). Para corrigir o corpo e tentar de novo, gere uma chave nova.
Respostas com retryable: true (por exemplo, 409 quando o anúncio ou o estoque está em uso por uma venda em andamento, ou 429 QUESTION_ANSWER_RATE_LIMIT) liberam a chave: reenvie a mesma requisição com a mesma chave depois de alguns segundos.

Endpoints v2

GET /api/v2/products - Listar anúncios com variantes e preço de cada uma
GET /api/v2/products/:id - Detalhe do anúncio com preço efetivo/base
POST /api/v2/products - Criar anúncio (single ou multi-variante com entrega automática)
PATCH /api/v2/products/:id - Atualizar anúncio (em anúncio com variantes, o preço muda pela rota de variantes)
PATCH /api/v2/products/:id/variants - Alterar preço e estoque das variantes de um anúncio dinâmico (retorno item a item, de 1 a 100 variantes por requisição)
POST /api/v2/products/:id/stock - Reabastecer o estoque de entrega automática (adiciona credenciais, com deduplicação). Aceita credentialsText ou items, e cada credencial pode levar referência (ref) e custo (costCents), que voltam em deliveredItems no pedido e no webhook order.delivered. Limites por requisição: 2000 itens, 5000 caracteres por item e 10000 itens no total por anúncio ou variante
PATCH /api/v2/products/bulk-price - Edição de preço em massa (retorno item a item, de 1 a 100 itens por requisição)
PATCH /api/v2/products/bulk-status - Ativar/desativar anúncios em massa (de 1 a 100 itens por requisição)
GET /api/v2/orders e GET /api/v2/orders/:id - Pedidos (vendas e compras). Nas vendas, deliveredItems traz a referência e o custo de cada credencial entregue, nunca o conteúdo dela
GET /api/v2/mediations e GET /api/v2/mediations/:orderId - Mediações (leitura)
GET /api/v2/reviews, GET /api/v2/reviews/stats, POST /api/v2/reviews/:reviewId/contest e GET /api/v2/contestations - Avaliações e contestações
GET /api/v2/questions, GET /api/v2/questions/:id e POST /api/v2/questions/:id/answer - Perguntas dos anúncios: listar (filtro por status, anúncio e ordem) e responder. Limite: 5 respostas por minuto e 20 por hora
GET /api/v2/balance e GET /api/v2/stats - Saldo e estatísticas
GET /api/v2/catalog/games - Catálogo de jogos com preço mínimo
GET /api/v2/me e GET /api/v2/usage - Identidade da chave e consumo atual

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

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.

Exemplos de payload (endpoints de escrita da v2)

Corpo de requisição aceito por cada endpoint de escrita. Todos os schemas da v2 são estritos: campo não documentado faz a requisição ser recusada com HTTP 400.

POST /api/v2/products

{   "title": "Conta Valorant Full Acesso",   "description": "Conta com skins raras e e-mail original incluído.",   "price": 9990,   "game": "valorant",   "category": "account",   "warrantyPeriod": 14,   "accountProvenance": "resale",   "listingType": "multiple",   "deliveryTime": "24h",   "autoDeliverySeparator": "--",   "imageUrls": [     "https://cdn.exemplo.com/conta-valorant.png"   ],   "variants": [     {       "title": "Primária",       "price": 9990,       "autoDeliveryItems": "login1:senha1--login2:senha2"     },     {       "title": "Secundária",       "price": 7990,       "stock": 5     }   ] }

PATCH /api/v2/products/:id

{   "price": 8990,   "isActive": true,   "warrantyPeriod": 14,   "deliveryTime": "24h" }

PATCH /api/v2/products/:id/variants

{   "items": [     {       "index": 0,       "price": 4490     },     {       "index": 2,       "price": 8990,       "stock": 7     }   ] }

POST /api/v2/products/:id/stock

{   "variantIndex": 0,   "items": [     {       "credential": "login1:senha1",       "ref": "LOTE12-001",       "costCents": 1500     },     {       "credential": "login2:senha2",       "ref": "LOTE12-002",       "costCents": 1790     }   ],   "dedupeMode": "skip" }

PATCH /api/v2/products/bulk-price

{   "items": [     {       "id": 9123,       "price": 4490     },     {       "id": 9311,       "price": 8990     }   ] }

PATCH /api/v2/products/bulk-status

{   "items": [     {       "id": 9123,       "isActive": false     },     {       "id": 9311,       "isActive": true     }   ] }

POST /api/v2/reviews/:reviewId/contest

{   "reason": "Avaliação injusta: o comprador não respondeu o suporte e abriu nota baixa." }

POST /api/v2/questions/:id/answer

{   "answer": "Sim, o e-mail original acompanha a conta e é entregue junto com o acesso." }

Limites e Quotas (v2)

Requisições por minuto: 60 (por conta)
Requisições por dia: 5000 (por conta)
Headers de limite em toda resposta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After

O limite é por conta: chaves v1 e v2 do mesmo vendedor compartilham o mesmo balde.

Como obter acesso

A v2 está em beta fechado: as chaves são emitidas pela equipe GameMarket para vendedores verificados, mediante solicitação via suporte. A API v1 permanece disponível para todos os vendedores verificados.

Códigos de erro

Códigos que a v2 devolve e o que a sua integração deve fazer em cada caso. Trate cada resposta pelo status HTTP e pelo campo code: o texto de message pode mudar.

400 - Preço acima do máximo por anúncio: Todo preço, inclusive o de cada variante e o de cada item da edição em massa, aceita no máximo 100000000 centavos (R$ 1.000.000,00). Acima disso, a requisição inteira é recusada com erro de validação (error "Validation error") que aponta o campo. Confira se o valor está em centavos e não foi multiplicado por 100 duas vezes.; Rotas: POST /api/v2/products · PATCH /api/v2/products/:id · PATCH /api/v2/products/:id/variants · PATCH /api/v2/products/bulk-price
400 - Credenciais demais na criação (TOO_MANY_CREDENTIALS): A soma das credenciais de todas as variantes passou de 10000 numa única criação (o campo limit traz o teto). Crie o anúncio com menos credenciais e reponha o restante em POST /api/v2/products/:id/stock.; Rotas: POST /api/v2/products
400 - Limites de entrega automática na criação: Variantes com autoDeliveryItems contam como entrega automática mesmo sem isAutoDelivery=true, e o teto passa a ser de 100 variantes. O texto de credenciais somado (autoDeliveryContent mais todas as variantes) aceita até 1000000 caracteres por requisição. As duas recusas são erros de validação no campo variants: crie com menos credenciais e reponha depois em POST /api/v2/products/:id/stock.; Rotas: POST /api/v2/products
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/v2/products/:id · PATCH /api/v2/products/bulk-status
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/v2/products/:id · PATCH /api/v2/products/bulk-status
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/v2/products/:id · PATCH /api/v2/products/bulk-status
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/v2/products/:id · PATCH /api/v2/products/bulk-status
400 - Anúncio sem estoque (NO_STOCK): Recusa ao reativar (isActive: true). Reponha o estoque antes de ativar: credenciais de entrega automática em POST /api/v2/products/:id/stock, estoque manual de variante em PATCH /api/v2/products/:id/variants e os demais casos pelo painel do vendedor.; Rotas: PATCH /api/v2/products/:id · PATCH /api/v2/products/bulk-status
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.; Rotas: PATCH /api/v2/products/:id
404 - Avaliação não encontrada: Avaliação inexistente ou de outro vendedor. O campo orderId do corpo é aceito por compatibilidade e ignorado: o pedido vinculado à contestação é sempre o da própria avaliação.; Rotas: POST /api/v2/reviews/:reviewId/contest
403 - E-mail não verificado (EMAIL_NOT_VERIFIED): Verifique o e-mail da conta no site para responder perguntas.; Rotas: POST /api/v2/questions/:id/answer
403 - Conta impedida de responder perguntas (QUESTIONS_BLOCKED): Sua conta está impedida de responder perguntas nos anúncios. Compras e vendas não são afetadas.; Rotas: POST /api/v2/questions/:id/answer
422 - Resposta não publicada (SECURITY_VIOLATION): Revise o texto e envie de novo com uma nova Idempotency-Key.; Rotas: POST /api/v2/questions/:id/answer
409 - Pergunta já respondida (ALREADY_ANSWERED): A pergunta já tem resposta. Não reenvie.; Rotas: POST /api/v2/questions/:id/answer
409 - Anúncio indisponível (PRODUCT_UNAVAILABLE): O anúncio da pergunta está pausado, em análise ou excluído. Responda quando o anúncio estiver ativo.; Rotas: POST /api/v2/questions/:id/answer
429 - Limite de respostas (QUESTION_ANSWER_RATE_LIMIT): Até 5 respostas por minuto e 20 por hora. Aguarde os segundos do header Retry-After e reenvie com a mesma Idempotency-Key.; Rotas: POST /api/v2/questions/:id/answer
403 - Conta de vendedor restrita (SELLER_RESTRICTED): A API fica suspensa enquanto a conta estiver restrita. Fale com o suporte.; Rotas: Todas as rotas

Em PATCH /api/v2/products/bulk-status, as recusas de reativação vêm item a item dentro de results, com HTTP 200: status "failed", error com o código em minúsculas (ex.: no_stock), code e message. Os demais itens do lote são aplicados normalmente.

Webhooks

Webhooks avisam o seu sistema quando algo acontece na sua conta, sem você precisar consultar a API o tempo todo. Eles valem para as chaves v1 e v2 e são configurados no painel, em Configurações → API/DEV, com até 5 webhooks ativos por conta.

Formato de toda notificação

O GameMarket envia um POST com JSON no corpo contendo event (nome do evento), timestamp (data em ISO 8601) e data (dados do evento). O header X-GameMarket-Event repete o nome do evento.

Regras de entrega

Responda com HTTP 2xx em até 10 segundos. Qualquer outro status, timeout ou erro de rede conta como falha.
Falhas são reenviadas, com até 5 tentativas no total e intervalos de 15 segundos, 1 minuto, 5 minutos e 30 minutos.
A URL precisa ser pública. Endereços de rede interna são recusados e redirecionamentos não são seguidos.
A mesma notificação pode chegar mais de uma vez. Processe de forma idempotente, usando o nome do evento junto com o id do pedido.

Webhook avisa, API confirma

Antes de qualquer ação com efeito no seu sistema (lançar a venda, liberar algo ao cliente), confirme os dados em GET /api/v2/orders/:id com a sua chave. Assim, uma requisição forjada para a sua URL não vira uma venda falsa.

Eventos de venda mais usados

sale.processing: Nova venda paga, em andamento.
order.delivered: A entrega automática enviou as credenciais ao comprador. Traz deliveredItems.
order.completed: Pedido concluído.
funds.released: Valor da venda liberado no seu saldo.
order.cancelled: Pedido cancelado, por exemplo PIX expirado sem pagamento.

Também há eventos de anúncio (criado, aprovado, recusado, esgotado), mediação, saque, saldo e avaliação, escolhidos ao criar o webhook.

Payload do order.delivered

Campos dentro de data:

id: ID numérico do pedido.
orderCode: Código do pedido (ex.: GM-7F3K9). Aceito em GET /api/v2/orders/:id.
productId, productTitle: ID e título do anúncio vendido.
buyerId, buyerName: ID e nome de usuário do comprador.
sellerId: O seu ID de vendedor.
deliveryType: Sempre auto neste evento.
itemsDelivered: Quantidade de itens entregues.
deliveredItems: Lista, na ordem da entrega, com a referência (ref) e o custo em centavos (costCents) que você cadastrou para cada credencial na reposição. Vem vazia quando os itens não tinham referência nem custo. A credencial em si nunca é enviada.

Webhooks do Discord recebem uma mensagem formatada no lugar do JSON acima, sem os headers X-GameMarket e sem deliveredItems.

Guia: lucro por venda

Para quem compra contas ou itens por custos diferentes e quer saber o lucro de cada venda sem abrir pedido por pedido.

1. Cadastre referência e custo na reposição

Reponha o estoque com items, uma entrada por credencial, informando a sua referência (ref) e o custo em centavos (costCents). A referência é um código seu, com 1 a 64 caracteres entre letras, números, ponto, hífen e sublinhado.

2. Receba a venda

Assine o webhook order.delivered. Quando a entrega automática envia a credencial ao comprador, o evento traz deliveredItems com a referência e o custo de cada item entregue.

3. Confirme e calcule

Confirme o pedido em GET /api/v2/orders/:id, que devolve o mesmo deliveredItems. O lucro da venda é o valor líquido (o price do pedido menos a taxa da plataforma) menos a soma dos costCents.

Bom saber

A referência não é secreta: aparece no pedido, no webhook e no painel. Nunca use login, e-mail ou senha nela.
Só o vendedor do pedido recebe deliveredItems. O comprador, consultando o mesmo pedido, não vê esse campo.
Credenciais cadastradas sem referência e vendas anteriores a este recurso retornam deliveredItems vazio.
Na Central de Entrega do painel você também pode informar uma referência e um custo para o lote inteiro. Assinantes Seller Pro têm essa conta feita automaticamente no Controle de Lucro.

Exemplos de Código

Disponíveis em 7 linguagens: cURL, JavaScript, Python, PHP, Ruby, Go e C#. O fluxo completo de um anúncio dinâmico: descobrir o índice de cada variante em GET /api/v2/products, alterar o preço da variante em PATCH /api/v2/products/:id/variants e reabastecer o estoque de entrega automática em POST /api/v2/products/:id/stock, sempre com o header Idempotency-Key nas escritas e leitura do resultado item a item.