عملیات هزینه‌بر

Idempotency-Key

POST /orders و POST /orders/{id}/renew برای هر سفارش یا تمدید جدید یک هدر Idempotency-Key یکتا لازم دارند. در صورت پایان مهلت درخواست، تلاش مجدد با همان مقدار امن است: درخواست تکمیل‌شده دوباره برگردانده می‌شود (meta.idempotent_replay: true) و هزینه هرگز دو بار کسر نمی‌شود.

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

import { randomUUID } from "node:crypto";

const key = randomUUID(); // همان مقدار در هر تلاش مجدد

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())  # همان مقدار در هر تلاش مجدد

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()

کلید چه زمانی آزاد می‌شود

• کلید فقط وقتی آزاد می‌شود که تلاش قطعاً هزینه‌ای کسر نکرده باشد: رد با 4xx یا خطای ارائه‌دهنده‌ای که هزینه‌اش بازگردانده شده است (details.refunded: true). در این حالت همان کلید یک تلاش جدید را آغاز می‌کند.
• هر کلید فقط برای یک عملیات است. فرستادن همان کلید با بدنه‌ای متفاوت (از جمله اهداف، نام و گزینه‌ها) یا استفاده از آن برای سفارش یا تمدیدی دیگر،400 invalid_request برمی‌گرداند. کلیدی که سفارشی ثبت کرده در تمدید، و کلیدی که در تمدید به کار رفته در سفارش پذیرفته نمی‌شود.
• 409 conflict همراه با details.order_id نشان می‌دهد که سفارشی که با آن کلید ثبت شده دیگر فعال نیست (پیش از آنکه بازگشت خودکار هزینه ممکن شود ناموفق شده یا لغو شده است). از کلید جدید استفاده کنید؛ اگر هزینه کسر شده است، با پشتیبانی تماس بگیرید.

آیا سفارش آماده است

meta.ready نشان می‌دهد که سفارش از همین حالا فعال است یا نه، و در پاسخ تکراری هم برمی‌گردد. در پیش‌سفارش، فعال‌سازی زمان‌بندی‌شده یا تأخیر ارائه‌دهنده، false می‌شود وmeta.warning پر می‌شود. سفارش را هنوز به کار نگیرید؛ با GET /orders/{id} به‌طور دوره‌ای بررسی کنید تا state برابر active شود.

اطلاعات ورود

نام کاربری و رمز عبور اختیاری‌اند. اگر آن‌ها را نفرستید، سیستم می‌سازد؛ اگر توکن مجوز proxies:read را هم داشته باشد، در پاسخ برمی‌گردند. انتخاب آن‌ها توسط خودتان مستلزم آن است که پلن شما اجازه دهد: به فیلد plan.custom_credentials در پاسخ /me نگاه کنید.

فیلدهای سفارش بر اساس نوع

✓ یعنی پذیرفته می‌شود، ✓* یعنی الزامی است و — یعنی در این نوع به کار نمی‌رود؛ مقدار داخل پرانتز، پیش‌فرضی است که اگر فیلد ارسال نشود استفاده می‌شود. فیلدهای ناشناخته رد می‌شوند؛ غلط املایی بی‌صدا نادیده گرفته نمی‌شود.

تغییر تنظیمات

تغییر تنظیماتی مانند نام سرویس و محدودیت ترافیک هزینه‌ای ندارد و با مجوز جداگانه‌ای (proxies:write) انجام می‌شود. این تغییرات Idempotency-Key لازم ندارند.