API de revendedor

Visión general

La API automatiza lo que haces a mano desde la página de compra: consultar tu saldo, comprobar el stock y el precio de un pedido, y luego comprar proxies ISP para Francia, España o Europa. Cada proxy es válido 30 días.

Una compra por API se comporta exactamente como una compra con saldo en el sitio:

• el importe se descuenta de tu saldo, con el descuento de tu nivel;
• se emite una factura, como en cualquier compra;
• los proxies se crean en tu cuenta y sus credenciales se te devuelven en la respuesta;
• se añaden a la página de Reventa de tu área de revendedor, con un precio de venta de 0 que fijas luego a mano (o que pasas en la solicitud).

Inicio rápido

1. Genera tu clave. En tu área de cliente, abre la pestaña «Área de revendedor», despliega el bloque «API de compra automática» y pulsa «Generar una clave». Cópiala enseguida: solo se muestra una vez.
2. Comprueba que funciona consultando tu saldo.
3. Haz un primer pedido.

Consultar el saldo:

export AIRPROXY_KEY="apr_votre_cle_ici"

curl https://airproxy.store/api/v1/reseller/balance \
  -H "Authorization: Bearer $AIRPROXY_KEY"

{ "ok": true, "balance": 94.3, "currency": "EUR" }

Comprar 2 proxies franceses:

curl -X POST https://airproxy.store/api/v1/reseller/buy \
  -H "Authorization: Bearer $AIRPROXY_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"fr","qty":2}'

{
  "ok": true,
  "order_id": 27,
  "country": "fr",
  "qty": 2,
  "total_debited": 5.4,
  "proxies": [
    {
      "proxy_id": "1791018004491.359791309",
      "host": "203.0.113.10",
      "port": 8888,
      "username": "airproxy4821",
      "password": "k3QxT9mW2vLp8dRa",
      "access": "203.0.113.10:8888:airproxy4821:k3QxT9mW2vLp8dRa",
      "country": "fr",
      "expires_at": "2026-11-02T09:00:04.491Z"
    },
    {
      "proxy_id": "1791018004492.928588261",
      "host": "203.0.113.10",
      "port": 8888,
      "username": "airproxy4822",
      "password": "8JZ5f1O7xG6jPrt5",
      "access": "203.0.113.10:8888:airproxy4822:8JZ5f1O7xG6jPrt5",
      "country": "fr",
      "expires_at": "2026-11-02T09:00:04.491Z"
    }
  ],
  "discount": 0.6,
  "balance": 88.9,
  "listed_in_resale": true
}

En Windows, sustituye $(uuidgen) por cualquier cadena única de 8 caracteres o más. Las direcciones de los ejemplos (203.0.113.10) son ficticias: usa siempre el host y el port de la respuesta.

Autenticación

Cada solicitud lleva tu clave de API en la cabecera Authorization. Se acepta la cabecera X-API-Key en su lugar.

Authorization: Bearer apr_votre_cle_ici

• Hay una sola clave por cuenta. Generar una nueva invalida la anterior de inmediato.
• No conservamos la clave en claro: si la pierdes, regenera una.
• Permite comprar con tu saldo y nada más. No da acceso ni a tu contraseña, ni a tus facturas, ni a tus medios de pago.
• Puedes revocarla en cualquier momento desde el mismo bloque de tu área de revendedor.
• Deja de funcionar (403 not_reseller) si se retira el modo revendedor de tu cuenta.

Convenciones

• Todas las rutas usan HTTPS. Las solicitudes con cuerpo envían Content-Type: application/json.
• Una respuesta correcta contiene "ok": true. Un error devuelve {"ok": false, "error": "...", "code": "..."} con el estado HTTP correspondiente y, según el caso, campos adicionales (balance, available...). Basa tu lógica en code, que es estable, nunca en error, que es un texto para humanos.
• Los importes son números en euros, con dos decimales como máximo. Las fechas van en formato ISO 8601, en UTC.
• Los tipos son estrictos: un número se pasa como número JSON ("qty": 2, no "qty": "2"). Un valor ambiguo se rechaza en lugar de interpretarse, porque esta API descuenta dinero.
• Los campos desconocidos de una solicitud se ignoran. Haz lo mismo con las respuestas: se les pueden añadir campos.
• Las respuestas nunca se almacenan en caché (Cache-Control: no-store): contienen credenciales.
• La API está pensada para llamarse desde tu servidor: las llamadas desde un navegador se bloquean.

Rutas

Las rutas siguientes son relativas a la URL base https://airproxy.store/api/v1/reseller. Los ejemplos leen tu clave de la variable AIRPROXY_KEY.

GET/balance

Devuelve tu saldo actual.

curl https://airproxy.store/api/v1/reseller/balance \
  -H "Authorization: Bearer $AIRPROXY_KEY"

import os
import requests

r = requests.get(
    "https://airproxy.store/api/v1/reseller/balance",
    headers={"Authorization": f"Bearer {os.environ['AIRPROXY_KEY']}"},
    timeout=15,
)
print(r.json())

const res = await fetch("https://airproxy.store/api/v1/reseller/balance", {
  headers: { Authorization: `Bearer ${process.env.AIRPROXY_KEY}` },
});
console.log(await res.json());

Respuesta 200

{ "ok": true, "balance": 94.3, "currency": "EUR" }

GET/stock

Devuelve, por cada país, el número de proxies disponibles y el precio de un pedido de qty proxies. Conviene consultarlo antes de una compra grande: el precio es decreciente, así que el precio unitario depende de la cantidad.

Parámetro de consulta

curl "https://airproxy.store/api/v1/reseller/stock?qty=5" \
  -H "Authorization: Bearer $AIRPROXY_KEY"

import os
import requests

r = requests.get(
    "https://airproxy.store/api/v1/reseller/stock",
    params={"qty": 5},
    headers={"Authorization": f"Bearer {os.environ['AIRPROXY_KEY']}"},
    timeout=15,
)
print(r.json())

const res = await fetch("https://airproxy.store/api/v1/reseller/stock?qty=5", {
  headers: { Authorization: `Bearer ${process.env.AIRPROXY_KEY}` },
});
console.log(await res.json());

Respuesta 200

{
  "ok": true,
  "currency": "EUR",
  "stock": [
    { "country": "fr", "available": 24, "qty": 5, "total": 12.6, "unit_price": 2.52 },
    { "country": "es", "available": 12, "qty": 5, "total": 9.5,  "unit_price": 1.9 },
    { "country": "eu", "available": 0,  "qty": 5, "total": 9.5,  "unit_price": 1.9 }
  ]
}

Los valores de este ejemplo son ficticios. El stock es común a todos los clientes: available puede cambiar de una llamada a otra.

POST/buy

Compra qty proxies de un país, por 30 días, descontando tu saldo. El pedido es todo o nada: si el saldo o el stock no bastan, no se descuenta nada.

Cabeceras

Cuerpo de la solicitud

curl -X POST https://airproxy.store/api/v1/reseller/buy \
  -H "Authorization: Bearer $AIRPROXY_KEY" \
  -H "Idempotency-Key: commande-4821" \
  -H "Content-Type: application/json" \
  -d '{"country":"fr","qty":2}'

import os
import requests

r = requests.post(
    "https://airproxy.store/api/v1/reseller/buy",
    headers={
        "Authorization": f"Bearer {os.environ['AIRPROXY_KEY']}",
        "Idempotency-Key": "commande-4821",
    },
    json={"country": "fr", "qty": 2},
    timeout=30,
)
data = r.json()
if r.status_code in (200, 201):
    for p in data["proxies"]:
        print(p["access"])
else:
    print(data["code"], data["error"])

const res = await fetch("https://airproxy.store/api/v1/reseller/buy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIRPROXY_KEY}`,
    "Idempotency-Key": "commande-4821",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ country: "fr", qty: 2 }),
});
const data = await res.json();
if (res.ok) data.proxies.forEach((p) => console.log(p.access));
else console.error(data.code, data.error);

En estos ejemplos, la clave de idempotencia se deriva del identificador de pedido de tu propio sistema, lo cual es la buena práctica (ver Idempotencia).

Respuesta 201

El pedido se crea. Repetir la misma solicitud devuelve el estado 200 con la cabecera Idempotent-Replay: true.

Objeto proxies[]

Idempotencia

Una compra descuenta tu saldo. Si la conexión se corta antes de la respuesta, no puedes saber si ocurrió. La cabecera Idempotency-Key, obligatoria en POST /buy, resuelve este problema: repetir la misma solicitud con la misma clave nunca descuenta dos veces. O bien la compra no había ocurrido y ocurre ahora, o bien ya había ocurrido y recibes el mismo pedido.

Elegir la clave

Derívala del identificador de pedido de tu propio sistema (commande-4821, ticket-98123...) y guárdala antes de la primera llamada. Si tu programa se reinicia a mitad del pedido, repetirá la misma clave en lugar de crear una nueva, y nunca pagará dos veces el mismo pedido.

Una clave tiene de 8 a 128 caracteres: letras, dígitos y . _ : -. Las claves son propias de tu cuenta. Nunca uses la misma clave para dos pedidos distintos, aunque pasen varias semanas.

Lo que devuelve una repetición

El pedido original, reconstruido a partir de su estado actual: las credenciales y el saldo son los de hoy. Los campos discount y listed_in_resale solo se devuelven en la creación. Solo se comparan country y qty: si repites con un price distinto, se devuelve el pedido original tal cual y su precio no se modifica.

Precios y descuentos

El precio de un pedido depende del país y de la cantidad (precio decreciente). GET /stock?qty=N devuelve el importe exacto que POST /buy descontará por N proxies en el momento de la llamada.

Tu descuento de nivel de revendedor se aplica automáticamente: tus niveles se muestran en la pestaña «Área de revendedor» de tu área de cliente. Si hay un descuento por reseña disponible y más ventajoso, es el que se aplica. Los códigos promocionales y la ruleta diaria no se aplican a las compras por API.

La respuesta de POST /buy indica el importe descontado (total_debited) y el descuento ya deducido (discount).

Después de la compra

La página de Reventa

Los proxies comprados por API se añaden automáticamente a la página de Reventa de tu área de revendedor, con el precio de venta pasado en price (0 si está ausente). Allí fijas luego el precio y el nombre del comprador cuando quieras, como con cualquier proxy.

Usar una credencial

El punto de entrada (host:port) es el mismo para todos tus proxies: es el nombre de usuario lo que designa cada proxy. Acepta SOCKS5 y HTTP (túnel CONNECT, por tanto para tráfico HTTPS). Reutiliza siempre host y port de la respuesta en lugar de escribirlos en duro. Para comprobar una credencial, pregunta al sitio qué dirección ve:

# SOCKS5
curl --proxy socks5h://USERNAME:PASSWORD@HOST:PORT https://airproxy.store/api/ip

# HTTP (tunnel CONNECT)
curl --proxy http://USERNAME:PASSWORD@HOST:PORT https://airproxy.store/api/ip

Caducidad y renovación

Cada proxy caduca en la fecha expires_at. La renovación no está disponible por la API: hazla desde la página de Reventa de tu área de cliente, donde se señalan las caducidades próximas.

Factura y saldo

Cada compra emite una factura, consultable en tu área de cliente como las demás. La recarga del saldo se hace desde el sitio, con tarjeta o en cripto: la API no tiene ruta de recarga.

Límites

• El tope de 24 horas cuenta los proxies pedidos, incluidos los de un pedido aún en curso. Un pedido rechazado antes de cualquier descuento (saldo, stock) no cuenta.
• La tasa por minuto cuenta todas las solicitudes autenticadas, incluidas las que se rechazan.
• Cada respuesta lleva las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (en segundos). Un rechazo 429 añade Retry-After.
• ¿Necesitas topes más altos? Contacta con el soporte indicando tu uso.

Errores

Todo error es un objeto JSON: ok vale false, code es el identificador estable que comprobar, error un mensaje legible. Algunos códigos añaden campos, indicados en la tabla.

{
  "ok": false,
  "error": "Solde insuffisant.",
  "code": "insufficient_balance",
  "balance": 1.2,
  "required": 5.4
}

Los dos errores order_failed son los únicos que no hay que repetir nunca: puede haberse movido dinero sin entrega, y solo el soporte puede resolver el pedido. Para todos los demás errores de red o de servidor, repetir con la misma Idempotency-Key no tiene riesgo.

Ejemplo completo

Esta función compra proxies y gestiona los cortes de red, los relés no disponibles y los límites de tasa repitiendo con la misma clave de idempotencia. Se detiene en cuanto un error no debe repetirse.

import os
import time
import requests

BASE = "https://airproxy.store/api/v1/reseller"
KEY = os.environ["AIRPROXY_KEY"]
RETRY_CODES = {"request_in_progress", "server_error"}


def acheter(country, qty, idem_key, price=None, essais=5):
    """Achète des proxies. Rejouer avec la même idem_key ne débite jamais deux fois."""
    body = {"country": country, "qty": qty}
    if price is not None:
        body["price"] = price

    for essai in range(essais):
        try:
            r = requests.post(
                f"{BASE}/buy",
                json=body,
                headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": idem_key},
                timeout=30,
            )
        except requests.RequestException:
            time.sleep(2 ** essai)  # coupure réseau : on rejoue avec la MÊME clé
            continue

        try:
            data = r.json()
        except ValueError:
            data = {}  # 502, 503, 504 d'un relais : corps non JSON

        if r.status_code in (200, 201):
            return data
        if r.status_code == 429 and data.get("code") == "rate_limited":
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        if r.status_code in (502, 503, 504) or data.get("code") in RETRY_CODES:
            time.sleep(2 ** essai)
            continue
        raise RuntimeError(f"{data.get('code')}: {data.get('error')}")  # à ne pas rejouer

    raise RuntimeError(f"Abandon après {essais} essais (clé {idem_key})")


# Servir un acheteur : la clé est dérivée de VOTRE identifiant de commande
commande = acheter("fr", 3, idem_key="commande-4821")
for p in commande["proxies"]:
    print(p["access"])

// Node.js 18 ou plus, module ES (fichier .mjs)
const BASE = "https://airproxy.store/api/v1/reseller";
const KEY = process.env.AIRPROXY_KEY;
const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Rejouer avec la même idemKey ne débite jamais deux fois.
async function acheter({ country, qty, price }, idemKey, essais = 5) {
  const body = { country, qty, ...(price != null && { price }) };

  for (let essai = 0; essai < essais; essai++) {
    let res;
    try {
      res = await fetch(`${BASE}/buy`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${KEY}`,
          "Idempotency-Key": idemKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(30000),
      });
    } catch {
      await pause(2 ** essai * 1000); // coupure réseau : on rejoue avec la MÊME clé
      continue;
    }

    const data = await res.json().catch(() => ({})); // 502, 503, 504 d'un relais : corps non JSON
    if (res.ok) return data;

    if (res.status === 429 && data.code === "rate_limited") {
      await pause(Number(res.headers.get("retry-after") ?? 5) * 1000);
      continue;
    }
    if ([502, 503, 504].includes(res.status) || ["request_in_progress", "server_error"].includes(data.code)) {
      await pause(2 ** essai * 1000);
      continue;
    }
    throw new Error(`${data.code}: ${data.error}`); // à ne pas rejouer
  }
  throw new Error(`Abandon après ${essais} essais (clé ${idemKey})`);
}

// Servir un acheteur : la clé est dérivée de VOTRE identifiant de commande
const commande = await acheter({ country: "fr", qty: 3 }, "commande-4821");
commande.proxies.forEach((p) => console.log(p.access));

Buenas prácticas

• Una clave de idempotencia por pedido, guardada antes de la llamada. Derívala del identificador de pedido de tu sistema.
• Nunca repitas un order_failed. Contacta con el soporte indicando el order_id.
• Trata out_of_stock como una respuesta normal. Avisa a tu comprador o vuelve a intentarlo más tarde, sin un bucle cerrado.
• Mantén un saldo suficiente para la noche. Un insufficient_balance no descuenta nada: tras la recarga, repite la misma clave.
• Conserva las credenciales entregadas con la referencia del pedido, en tu base de datos. Una repetición devuelve el estado actual del pedido, no su estado original.
• No consultes el stock en bucle. Una llamada cada pocos segundos basta de sobra, y dispones de 30 solicitudes por minuto.
• Vigila expires_at y renueva antes del vencimiento desde tu área de cliente.
• Mantén la clave en secreto y regenérala a la menor duda.

Soporte

¿Una pregunta o un comportamiento inesperado? Abre un ticket desde tu área de cliente, o escríbenos por Discord. Indica la referencia order_id del pedido en cuestión, la hora de la llamada y el código de error recibido: así podemos encontrar la solicitud enseguida.

Historial

3 de octubre de 2026: primera versión, con las rutas balance, stock y buy.