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
- O cliente paga no seu site. Agora você tem produto, ID do jogador, região e o seu próprio número de pedido.
- Seu servidor cria o pedido no fornecedor com um
POST. Recebe de volta umorder_iddo fornecedor e o statuspending. - O fornecedor avisa o seu servidor com um webhook assinado assim que o pedido vira
deliveredoufailed. (Ou o seu servidor consulta o status a cada 30–60 segundos — os dois funcionam.) - 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 API | O 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_reason | Reembolsar 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 umproduct_keydeGET /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 mesmobuyer_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.