Operaciones con cargo

Idempotency-Key

POST /orders y POST /orders/{id}/renew requieren un encabezado Idempotency-Key único para cada pedido o renovación nuevos. Ante un tiempo de espera agotado, es seguro reintentar con el mismo valor: se devuelve la solicitud ya completada (meta.idempotent_replay: true) y nunca se cobra dos veces.

Idempotency-Key: 3f7a1c9e-2b48-4d51-9c3a-8e6f0d215b47

import { randomUUID } from "node:crypto";

const key = randomUUID(); // el MISMO valor en cada reintento

async function createOrder(body) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch("https://api.proxynet.io/api/v1/orders", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.PROXYNET_TOKEN}`,
        "Idempotency-Key": key,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });
    if (res.status === 409 && res.headers.get("retry-after")) {
      await new Promise((r) => setTimeout(r, Number(res.headers.get("retry-after")) * 1000));
      continue;
    }
    return res.json();
  }
}

import os, time, uuid, requests

key = str(uuid.uuid4())  # el MISMO valor en cada reintento

def create_order(body):
    for _ in range(3):
        res = requests.post(
            "https://api.proxynet.io/api/v1/orders",
            headers={
                "Authorization": f"Bearer {os.environ['PROXYNET_TOKEN']}",
                "Idempotency-Key": key,
            },
            json=body,
        )
        if res.status_code == 409 and "Retry-After" in res.headers:
            time.sleep(int(res.headers["Retry-After"]))
            continue
        return res.json()

Cuándo se libera la clave

• La clave solo se libera si es seguro que el intento no cobró nada: un rechazo 4xx o un error del proveedor con el cargo reembolsado (details.refunded: true). En ese caso, la misma clave inicia un intento nuevo.
• Una clave sirve para una sola operación. Enviar la misma clave con un cuerpo distinto (incluidos los destinos, el nombre y las opciones) o usarla para otro pedido u otra renovación devuelve400 invalid_request. Una clave que abrió un pedido no se acepta en una renovación, y una clave usada en una renovación no se acepta en un pedido.
• Un 409 conflict con details.order_id indica que el pedido abierto con esa clave ya no está vigente (falló sin que se pudiera reembolsar automáticamente o se canceló). Usa una clave nueva; si se te cobró, ponte en contacto con soporte.

¿Está listo el pedido?

meta.ready indica si el pedido ya está activo, también en la respuesta de un reintento. En un pedido anticipado, una activación programada o un retraso del proveedor esfalse y meta.warning llega con contenido. No pongas todavía el pedido en uso; consulta periódicamente GET /orders/{id} hasta questate sea active.

Credenciales

El nombre de usuario y la contraseña son opcionales. Si no los envías, el sistema los genera; se devuelven en la respuesta si el token también tiene proxies:read. Para elegirlos tú mismo, tu plan debe permitirlo: consulta el campo plan.custom_credentials en la respuesta de /me.

Campos del pedido por tipo

✓ se acepta, ✓* es obligatorio, — no se usa en este tipo; el valor entre paréntesis es el predeterminado que se usa si no se envía el campo. Los campos desconocidos se rechazan; un error tipográfico no se ignora en silencio.

Cambios de configuración

Los cambios de configuración, como el nombre del servicio y el límite de tráfico, no generan cargos y se hacen con un permiso aparte (proxies:write). No requieren Idempotency-Key.