Cuando un revendedor pasa de unas decenas de pedidos al día, copiar IDs del chat al panel del proveedor deja de escalar. La solución es una API de pedidos: tu sitio recoge el ID del jugador y el pago, envía el pedido al proveedor automáticamente y le muestra al cliente un estado en vivo. Esta guía recorre el flujo usando la API de pedidos de RechargeGames; el patrón es el mismo para cualquier proveedor.
El flujo en cuatro pasos
- El cliente paga en tu sitio. Ahora tienes producto, ID de jugador, región y tu propio número de pedido.
- Tu servidor crea el pedido en el proveedor con un
POST. Recibes unorder_iddel proveedor y el estadopending. - El proveedor avisa a tu servidor con un webhook firmado en cuanto el pedido pasa a
deliveredofailed. (O tu servidor consulta el estado cada 30–60 segundos — ambas cosas funcionan.) - Tu sitio le muestra al cliente “Procesando → Entregado”, y si falla, le reembolsa.
Nada de esto ocurre en el navegador. La clave de la API vive en tu servidor; una clave en el JavaScript del navegador la ve cualquier visitante.
Paso 2 en detalle: crear el pedido de forma segura
Empieza por la lista de precios del proveedor: GET /v1/products devuelve todos los paquetes a tu precio, cada uno con un product_key. Envía esa clave con el pedido y pagas exactamente el precio de la lista — sin sorpresas si armaste tu propia tabla de precios ayer.
El otro campo que más importa es buyer_ref — tu propio número de pedido. Envíalo en cada creación. Si la petición expira y reintentas, el proveedor ve el mismo buyer_ref, devuelve el pedido existente y no entrega dos veces. Sin eso, un momento de red inestable puede recargar a un jugador dos veces mientras a ti te pagaron una.
curl -X POST https://api.rechargegame.games/v1/orders \
-H "X-API-Key: gv_live_..." \
-H "Content-Type: application/json" \
-d '{
"product": "Free Fire 110 Diamonds",
"product_key": "topup/free-fire/latam/110 Diamonds",
"region": "LATAM",
"player_id": "51234567",
"buyer_ref": "TIENDA-10231"
}'
Trata 201 (creado) y 200 (ya existía) como éxito. Pon un timeout de 20 segundos y reintenta la misma petición ante errores de red.
Pon la región en el campo region, no en el nombre del producto. Mantiene el pedido legible del lado del proveedor y evita que “Free Fire 520 (MX)” se entregue en el servidor equivocado.
¿Aún no quieres gastar nada? Añade "test": true al pedido: no se cobra ni se entrega nada, y termina solo en unos diez segundos — así armas y compruebas todo el flujo antes.
Paso 3 en detalle: webhooks primero, consulta como red de seguridad
Registra la dirección de tu webhook una sola vez en el panel del proveedor. Cuando un pedido pasa a delivered o failed, el proveedor te envía el pedido con un POST, firmado para que compruebes que de verdad viene de él. Responde con cualquier 2xx en menos de diez segundos; si no lo haces, se reintenta a 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas. Usa la cabecera webhook-id para ignorar la repetición de un evento que ya trataste.
Un webhook aún puede perderse — tu servidor puede estar caído un día entero. Por eso mantén una red de seguridad lenta: una tarea que revise tus pedidos “pendientes” cada pocos minutos con GET /v1/orders/{order_id}. Las lecturas de estado no tienen límite de tasa, y el estado ahí es siempre la verdad. Si solo consultas, un intervalo razonable es 30 segundos durante los primeros diez minutos y 60 segundos después. Detente cuando el estado sea delivered o failed — ambos son finales.
Si usas WordPress o una tienda pequeña en PHP, un cron cada minuto que revise tus pedidos pendientes es suficiente. No necesitas un sistema de colas hasta pasar de varios miles de pedidos al día.
Qué mostrarle al cliente
Mantén tres estados y mapea los estados de la API a ellos:
| Estado de la API | El cliente ve | Tu acción |
|---|---|---|
pending | “Procesando — normalmente en menos de 20 minutos” | Esperar el webhook |
delivered | “Entregado ✓” más cualquier delivery_note (un código, en productos de código) | Marcar pagado y listo |
failed | “No se pudo entregar — reembolsado” más una versión amigable de failure_reason | Reembolsar al cliente; el proveedor ya devolvió a tu saldo |
Muestra el failure_reason del proveedor solo después de reescribirlo. “Region mismatch” debe convertirse en “Esta cuenta no está en el servidor LATAM — revisa la región y pide de nuevo.”
Errores que vas a ver de verdad
422 invalid_request— falta un campo o un valor es demasiado largo. El mensaje nombra el campo. Corrige la validación de tu formulario; no reintentes.422 unknown_product— no se encontró precio para ese producto, así que no se creó nada. Usa unproduct_keydeGET /v1/products.409 out_of_stock— ese paquete está agotado ahora mismo. No se creó ni se cobró nada. Muéstrale otro paquete al cliente, o esconde el paquete hasta que la lista de precios vuelva a mostrarlo.402 insufficient_balance— tu saldo es menor que el precio. Carga saldo y reintenta con el mismobuyer_ref.401 invalid_api_key— la clave es incorrecta, está desactivada o fue rotada. Alértate; no reintentes en bucle.429 rate_limited— más de 60 creaciones de pedido en un minuto. Espera un minuto. Si llegas a esto en operación normal, tienes volumen suficiente para pedir un límite mayor.- Timeouts — reintenta con el mismo
buyer_ref. Para eso existe exactamente la idempotencia.
Una implementación mínima
En Python, toda la integración son dos funciones:
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()
Las versiones en Node.js y PHP, el formato del webhook y todos los códigos de error están en la página de la API y en la documentación completa. Para obtener una clave: crea una cuenta gratis y solicita el acceso a la API en tu panel (Perfil → Acceso a la API). Lo aprobamos tras una revisión rápida; después creas y rotas tu clave tú mismo.