1. Início
  2. Guias para revendedores
  3. Conecte seu site de recargas a uma API de pedidos

Conecte seu site de recargas a uma API de pedidos

O fluxo que um site de revenda precisa — criar, receber o aviso por webhook, mostrar status — com a idempotência e o tratamento de erros que evitam cobrar o cliente duas vezes.

Publicado em · 6 min de leitura

Quando um revendedor passa de algumas dezenas de pedidos por dia, copiar IDs do chat para o painel do fornecedor deixa de escalar. A solução é uma API de pedidos: seu site coleta o ID do jogador e o pagamento, envia o pedido ao fornecedor automaticamente e mostra ao cliente um status ao vivo. Este guia percorre o fluxo usando a API de pedidos da RechargeGames; o padrão é o mesmo para qualquer fornecedor.

O fluxo em quatro passos

  1. O cliente paga no seu site. Agora você tem produto, ID do jogador, região e o seu próprio número de pedido.
  2. Seu servidor cria o pedido no fornecedor com um POST. Recebe de volta um order_id do fornecedor e o status pending.
  3. O fornecedor avisa o seu servidor com um webhook assinado assim que o pedido vira delivered ou failed. (Ou o seu servidor consulta o status a cada 30–60 segundos — os dois funcionam.)
  4. Seu site mostra ao cliente “Processando → Entregue”, e em caso de falha reembolsa.

Nada disso acontece no navegador. A chave da API fica no seu servidor; uma chave no JavaScript do navegador é visível para qualquer visitante.

Passo 2 em detalhe: criando o pedido com segurança

Comece pela lista de preços do fornecedor: GET /v1/products devolve todos os pacotes ao seu preço, cada um com um product_key. Envie essa chave com o pedido e você paga exatamente o preço da lista — sem surpresas se você montou a sua própria tabela de preços ontem.

O outro campo mais importante é o buyer_ref — o seu próprio número de pedido. Envie em toda criação. Se a requisição der timeout e você tentar de novo, o fornecedor vê o mesmo buyer_ref, devolve o pedido existente e não entrega duas vezes. Sem isso, um momento de rede instável pode recarregar um jogador duas vezes enquanto você recebeu uma.

curl -X POST https://api.rechargegame.games/v1/orders \
  -H "X-API-Key: gv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Free Fire 100 Diamonds",
    "product_key": "topup/free-fire/brazil/100 Diamonds",
    "region": "Brazil",
    "player_id": "51234567",
    "buyer_ref": "LOJA-10231"
  }'

Trate 201 (criado) e 200 (já existia) como sucesso. Defina timeout de 20 segundos e repita a mesma requisição em erros de rede.

Coloque a região no campo region, não no nome do produto. Mantém o pedido legível do lado do fornecedor e evita que “Free Fire 520 (BR)” seja entregue no servidor errado.

Ainda não quer gastar nada? Adicione "test": true ao pedido: nada é cobrado nem entregue, e ele termina sozinho em cerca de dez segundos — assim você monta e confere o fluxo inteiro antes.

Passo 3 em detalhe: webhooks primeiro, consulta como rede de segurança

Cadastre o endereço do seu webhook uma vez no painel do fornecedor. Quando um pedido vira delivered ou failed, o fornecedor envia o pedido para você com um POST, assinado para você conferir que veio mesmo dele. Responda com qualquer 2xx em até dez segundos; se não responder, ele é reenviado após 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas. Use o header webhook-id para ignorar a repetição de um evento que você já tratou.

Um webhook ainda pode se perder — seu servidor pode ficar fora do ar um dia inteiro. Por isso mantenha uma rede de segurança lenta: uma tarefa que confere seus pedidos “pendentes” a cada poucos minutos com GET /v1/orders/{order_id}. As leituras de status não têm limite de taxa, e o status ali é sempre a verdade. Se você só consulta, um intervalo sensato é 30 segundos nos primeiros dez minutos e 60 segundos depois. Pare quando o status for delivered ou failed — os dois são finais.

Se você usa WordPress ou uma loja pequena em PHP, um cron a cada minuto que varre seus pedidos pendentes já basta. Você não precisa de sistema de filas até passar de alguns milhares de pedidos por dia.

O que mostrar ao cliente

Mantenha três estados e mapeie os status da API para eles:

Status da APIO cliente vêSua ação
pending“Processando — normalmente em menos de 20 minutos”Aguardar o webhook
delivered“Entregue ✓” mais qualquer delivery_note (um código, em produtos de código)Marcar pago e concluído
failed“Não foi possível entregar — reembolsado” mais uma versão amigável do failure_reasonReembolsar o cliente; o fornecedor já devolveu ao seu saldo

Mostre o failure_reason do fornecedor só depois de reescrever. “Region mismatch” deve virar “Esta conta não está no servidor Brasil — confira a região e peça de novo.”

Erros que você vai ver de verdade

  • 422 invalid_request — falta um campo ou um valor é longo demais. A mensagem diz qual campo. Corrija a validação do formulário; não repita.
  • 422 unknown_product — nenhum preço foi encontrado para esse produto, então nada foi criado. Use um product_key de GET /v1/products.
  • 409 out_of_stock — esse pacote está sem estoque agora. Nada foi criado nem cobrado. Mostre outro pacote ao cliente, ou esconda o pacote até a lista de preços voltar a mostrá-lo.
  • 402 insufficient_balance — seu saldo é menor que o preço. Carregue saldo e repita com o mesmo buyer_ref.
  • 401 invalid_api_key — chave errada, desativada ou trocada. Alerte a si mesmo; não repita em loop.
  • 429 rate_limited — mais de 60 criações de pedido num minuto. Espere um minuto. Se isso acontece em operação normal, você tem volume suficiente para pedir um limite maior.
  • Timeouts — repita com o mesmo buyer_ref. É exatamente para isso que serve a idempotência.

Uma implementação mínima

Em Python, a integração inteira são duas funções:

import os, requests

API = "https://api.rechargegame.games"
KEY = os.environ["GV_API_KEY"]

def create_order(product_key, product, player_id, region, buyer_ref):
    r = requests.post(f"{API}/v1/orders", timeout=20,
        headers={"X-API-Key": KEY},
        json={"product_key": product_key, "product": product,
              "player_id": player_id, "region": region,
              "buyer_ref": buyer_ref})
    r.raise_for_status()
    return r.json()["order_id"]

def status(order_id):
    r = requests.get(f"{API}/v1/orders/{order_id}", timeout=20,
        headers={"X-API-Key": KEY})
    r.raise_for_status()
    return r.json()

As versões em Node.js e PHP, o formato do webhook e todos os códigos de erro estão na página da API e na documentação completa. Para obter uma chave: crie uma conta grátis e peça o acesso à API no painel (Perfil → Acesso à API). Aprovamos após uma checagem rápida; depois você mesmo cria e troca a sua chave.

← Todos os guias

Pronto para começar a vender?

Abra uma conta grátis e tenha preço de atacado desde o primeiro pedido. Dúvidas? Nosso suporte está no Telegram.