صدور کارت هدیه و eSIM با یک فراخوانی
یک کاتالوگ برای همهٔ خانوادههای محصول. هر سفارش در همان لحظهٔ ثبت قیمتگذاری میشود و هرگز از سقفی که تعیین میکنید بالاتر نمیرود، در برابر کیف پول پیشپرداخت شما ایمن در برابر تکرار است و وبهوکها امضا میشوند — پس تلاشهای مجدد ایمناند و روز راهاندازی بیماجرا میگذرد.
پس از تأیید فضای کاری شما، کلیدهای API در داشبورد پذیرنده صادر و مدیریت میشوند.
روند یک سفارش
یک چرخهٔ کوتاه — سه فراخوانی و یک وبهوک امضاشده — و این چرخه برای همهٔ خانوادههای محصول یکسان است.
یافتن محصول
GET /products
یک کاتالوگ واحد از کارتهای هدیه، بستههای eSIM و شارژها را بر اساس دستهبندی، کشور یا متن مرور کنید — یا دقیقاً همان محصولاتی را که میفروشید با شناسه بهروز کنید.
ثبت سفارش
POST /orders
قلم مورد نظر را بفرستید: در یک فراخوانی قیمتگذاری و سفارش داده میشود، هرگز بالاتر از سقفی که تعیین کردهاید. تکرار درخواست با همان کلید، همان سفارش را برمیگرداند.
دریافت وبهوک
order.fulfilled
یک رویداد امضاشده همان لحظهای که تحویل کامل شود به شما اطلاع میدهد. بدون حلقههای پرسوجوی مکرر.
نمایش کد
POST /orders/{id}/fulfillment
کدها و PINها را از طریق یک اندپوینت اختصاصی و ممیزیشده دریافت کنید — هرگز کش نمیشوند و هر بار نمایش شمارش میشود.
به زبان برنامهنویسی خودتان، با HTTPS ساده
یک REST API تمیز و قابل پیشبینی — ورودی JSON، خروجی JSON، یک هدر X-Api-Key و بدون نیاز به SDK. جستوجو، سفارش، نمایش کد: اولین سفارش شما فقط سه فراخوانی است.
const BASE = "https://integration.xegora.com/api/v1";const response = await fetch(`${BASE}/orders`, { method: "POST", headers: { "X-Api-Key": process.env.XEGORA_API_KEY!, "Content-Type": "application/json", "Idempotency-Key": "order-10231", }, body: JSON.stringify({ clientReference: "po-10231", item: { productId, variantId, quantity: 1, currency: "USD" }, maximumTotal: 60.0, // the price your buyer saw }),});const order = await response.json();// 409 price_above_maximum carries quotedTotal — show the new price insteadconsole.log(order.status); // "reserved" — wait for "fulfilled", then reveal- سفارشهای ایمن در برابر تکرار
- وبهوکهای امضاشده
- کلیدهای API با دسترسی محدود
- کیف پول پیشپرداخت
بخشهای اصلی API، از ابتدا تا انتها
ساختار واقعی درخواست و پاسخ — روی هر ردیف کلیک کنید. برداشتها، تاریخچهٔ واریز و تصاویر محصول بقیهٔ API را تکمیل میکنند؛ مرجع کامل در docs.xegora.com قرار دارد.
POST /api/v1/orders
سفارش از محل کیف پول پیشپرداخت شما: قلم مورد نظر را بفرستید تا در یک فراخوانی قیمتگذاری و سفارش داده شود (با maximumTotal اختیاری)، یا یک quoteId بفرستید. هدر Idempotency-Key الزامی است — تلاش مجدد همان سفارش را برمیگرداند. دامنهٔ دسترسی: orders.create.
{
"id": "0198e000-1111-7abc-9def-222233334444",
"clientReference": "po-10231",
"status": "reserved",
"total": 58.50,
"currency": "USD",
"lines": [
{ "productId": "0198d72d-99d6-75a6-9f12-971050ba7a5f", "variantId": "0198d72d-a15b-7cbf-…",
"productName": "Everyday Digital Gift Card", "variantLabel": "50", "quantity": 1,
"unitPrice": 58.50, "currency": "USD", "faceValue": 50, "faceCurrency": "EUR" }
],
"createdAtUtc": "2026-09-05T12:01:02Z",
"updatedAtUtc": "2026-09-05T12:01:02Z"
}زیرساخت بیدردسری که واقعاً میخواهید
هر آنچه یک یکپارچهسازی صدور را در برابر ترافیک واقعی پایدار نگه میدارد — ایمنی در برابر تکرار، امضاها، اعتبارنامههای با دسترسی محدود و کیف پولی که امکان خرج بیش از موجودی ندارد.
کاتالوگ یکپارچه
کارتهای هدیه، بستههای eSIM و شارژ موبایل یک ساختار داده، یک منبع قیمت و یک روند سفارش مشترک دارند. یک بار یکپارچهسازی کنید تا هر محصولی که Xegora اضافه میکند بهطور خودکار در اختیار شما باشد.
سفارشهای ایمن در برابر تکرار
ایجاد سفارش و نمایش تحویل هر دو هدر Idempotency-Key میپذیرند. قطعی لحظهای شبکه، پایان مهلت، حلقهٔ تلاش مجدد پرشتاب — درخواست را هر چند بار که خواستید تکرار کنید؛ دقیقاً یک سفارش ثبت میشود.
وبهوکهای امضاشده
رویدادهای order.processing، order.fulfilled، order.failed، order.refunded و wallet.credited از طریق HTTPS با امضای HMAC-SHA256 (X-Xegora-Signature) و با تضمین تحویل دستکم یکباره ارسال میشوند و موارد تکراری با یک X-Xegora-Event-Id ثابت حذف میشوند.
کلیدهای با حداقل دسترسی
هر کلید مجموعهٔ مشخصی از دامنههای دسترسی دارد — خواندن کاتالوگ، دریافت پیشفاکتور قیمت، ثبت سفارش، خواندن کیف پول و دامنههای مربوط به جابهجایی پول همگی از هم جدا هستند — بهعلاوهٔ فهرست مجاز CIDR و تاریخ انقضای اختیاری. ابطال فوری است.
کیف پول پیشپرداخت
سفارشها مبلغ را از موجودی پیشپرداخت شما رزرو میکنند و هنگام تحویل، کسر نهایی انجام میشود؛ در صورت ناموفق بودن، رزرو بهطور خودکار آزاد میشود. موجودی را بهصورت درونزنجیرهای از طریق یک آدرس واریز دائمی تأمین کنید و وجوه استفادهنشده را فقط به اطلاعات تسویهٔ ثبتشدهٔ خودتان برداشت کنید.
کاتالوگی ساختهشده برای انتخاب
بر اساس دستهبندی، کشور یا متن جستوجو کنید، نتایج را به مبالغ ثابت یا دلخواه محدود کنید و محصولاتی را که میفروشید با شناسه و در یک فراخوانی بهروز کنید — همراه با مراحل استفاده و سایر کشورهای برند برای هر محصول، با قیمتگذاری به ارز فروش شما.
قیمتهای عمده، بدون غافلگیری
پیشفاکتور قیمت، همان قیمت است. سایر شرایط تجاری شما هنگام راهاندازی فضای کاری پذیرنده توافق میشود.
- قیمتگذاری عمدهٔ محصولات به ارز فروش شما — مبلغ کل پیشفاکتور دقیقاً همان مبلغی است که از کیف پول شما کسر میشود
- بدون کارمزد پنهان بهازای هر فراخوانی؛ محدودیت نرخ ثابت 120 درخواست در دقیقه برای هر فضای کاری
- طرح فضای کاری شما (راهاندازی و شرایط) در فرایند عضویت پذیرنده توافق میشود
- برداشت وجوه استفادهنشده بهصورت شفاف اعلام میشود — کارمزد، مبلغ خالص و تاریخ تسویه از ابتدا مشخص است
آمادهاید اولین سفارش خود را صادر کنید؟
از حساب کاربری خود برای فضای کاری پذیرنده درخواست دهید، تأیید بگیرید و کلیدهای API با دسترسی محدود را از داشبورد صادر کنید — آنوقت اولین سفارش شما تنها سه فراخوانی فاصله دارد. مرجع کامل در docs.xegora.com منتظر شماست.