Idempotency

گاهی شبکه قطع می‌شود و نمی‌فهمید برداشت ثبت شد یا نه. راهش ساده است: همان درخواست را با همان Idempotency-Key دوباره بفرستید. برداشت دومی ساخته نمی‌شود.

این هدر برای این مسیرها لازم است:

• POST /v1/transactions
• POST /v1/addresses
• POST /v1/addresses/batch

کلید 1 تا 255 نویسه‌ی ASCII چاپی بی فاصله است، مثل شناسه‌ی درخواست برداشت در سیستم خودتان. پیشوند rebuild: رزرو است.

چه پاسخی می‌گیرید

حالت	برداشت	آدرس
همان کلید، همان درخواست	200 و همان تراکنش اول، با "created": false	201 و همان آدرس
همان کلید، درخواست دیگر	409 با {"error":"already exists"}	409
کلید تازه	برداشت تازه با 201	آدرس تازه با 201

برای برداشت، «همان درخواست» یعنی همه‌ی فیلدها جز expires_at⁠. تکرار با expires_at دیگر همان تراکنش اول را برمی‌گرداند.

قانون‌ها

• هر کلید برای هر کلید API سازمان برای همیشه یکتاست. آن را برای برداشت دیگری دوباره به کار نبرید.
• Idempotency-Key جزو رشته‌ی امضاست، پس در راه عوض نمی‌شود.
• کلید را از شناسه‌ی پایدار درخواست بسازید، نه از زمان یا عدد تصادفی.
• کلید را پیش از فرستادن در سیستم خودتان ذخیره کنید. اگر برنامه‌ی شما وسط کار افتاد، با همان کلید ادامه دهید.

چه وقت دوباره بفرستید

نتیجه	کار شما
قطع شبکه، timeout، 429⁠، 503	با فاصله‌ی رو به افزایش و با همان کلید دوباره بفرستید
400⁠، 401⁠، 403⁠، 409	دوباره فرستادن همان درخواست فایده ندارد. درخواست را درست کنید. یک استثنا: 409 با insufficient_balance چیزی ثبت نمی‌کند؛ پس از شارژ آدرس، با همان کلید می‌توانید دوباره بفرستید

برای تکرار کلید تازه نسازید

اگر جوابی نگرفتید، همان درخواست را با همان کلید بفرستید. با کلید تازه ممکن است پول دو بار برود.

نمونه

import { romu } from "./romu.ts";

const body = {
  wallet_id, asset: "TRON_USDT",
  amount: "100.50", to_address, expires_at, external_ref: "user-1207",
};

const r = await romu.post("/v1/transactions", { idempotencyKey: "withdraw-8841", json: body });
// 201: created. 200: the same request again, the first transaction.
console.log(r.status, r.body.transaction.id, r.body.created);