1. Inicio
  2. Guías para revendedores
  3. Conecta tu sitio de recargas a una API de pedidos

Conecta tu sitio de recargas a una API de pedidos

El flujo que necesita un sitio de reventa — crear, recibir el aviso por webhook, mostrar estado — con la idempotencia y el manejo de errores que evitan cobrarle dos veces al cliente.

Publicado el · 6 min de lectura

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

  1. El cliente paga en tu sitio. Ahora tienes producto, ID de jugador, región y tu propio número de pedido.
  2. Tu servidor crea el pedido en el proveedor con un POST. Recibes un order_id del proveedor y el estado pending.
  3. El proveedor avisa a tu servidor con un webhook firmado en cuanto el pedido pasa a delivered o failed. (O tu servidor consulta el estado cada 30–60 segundos — ambas cosas funcionan.)
  4. 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 APIEl cliente veTu 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_reasonReembolsar 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 un product_key de GET /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 mismo buyer_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.

← Todas las guías

¿Listo para empezar a vender?

Abre una cuenta gratis y obtén precio mayorista desde tu primer pedido. ¿Dudas? Nuestro soporte está en Telegram.