跳到主要内容
Xegora 集成 API v1

一次调用即可发放礼品卡与 eSIM

所有产品线共用一个目录。订单在您下单的那一刻定价，且绝不超过您设定的上限；针对您的预付钱包，下单具备幂等性；Webhook 均带签名——因此重试安全无虞，上线当天也波澜不惊。

成为商户阅读文档

工作区获批后，即可在商户控制台中签发和管理 API 密钥。

生命周期

订单流程

一个简短的闭环——三次调用加一个签名 Webhook——所有产品线都使用同一个闭环。

  1. 查找商品

    GET /products

    在同一个目录中按类别、国家/地区或关键词浏览礼品卡、eSIM 套餐和话费充值——或按 ID 精确刷新您销售的商品。

  2. 提交订单

    POST /orders

    发送商品：一次调用即可完成定价和下单，价格绝不超过您设定的上限。使用相同的幂等键重放请求将返回同一订单。

  3. 接收 Webhook

    order.fulfilled

    交付完成的那一刻，带签名的事件就会通知您。无需轮询。

  4. 显示兑换码

    POST /orders/{id}/fulfillment

    通过专用且经审计的端点获取兑换码和 PIN 码——从不缓存，每次查看都有记录。

快速入门

任意编程语言，纯 HTTPS

简洁、可预期的 REST API——JSON 输入，JSON 输出，只需一个 X-Api-Key 请求头，无需 SDK。查找、下单、取码：三次调用即可完成您的第一笔订单。

create-order.ts
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 instead
console.log(order.status); // "reserved" — wait for "fulfilled", then reveal
  • 幂等下单
  • 签名 Webhook
  • 限定范围的 API 密钥
  • 预充值钱包
API 参考

核心接口，端到端全覆盖

真实的请求和响应结构——点击任意一行即可查看。提现、充值历史和商品图片等接口让功能更加完整；完整参考文档请见 docs.xegora.com。

POST /api/v1/orders

使用预付钱包下单：发送要定价的商品，一次调用即可完成定价和下单（可附带 maximumTotal），或者发送 quoteId。必须提供 Idempotency-Key 请求头——重试将返回同一订单。权限范围：orders.create。

响应示例202 Accepted
{
  "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"
}

其他所有内容请见 docs.xegora.com

完整的开发者文档——包含每个端点的请求和响应结构、三种语言的 Webhook 签名验证示例，以及完整的 OpenAPI 3.1 规范。

  • 快速入门
  • 身份验证
  • 订单与报价
  • Webhook
  • 上线
为生产环境而生

您真正想要的“无聊”基础设施

让发放集成经得起真实流量考验的一切——幂等性、签名、限定范围的凭据，以及不会超支的钱包。

统一目录

礼品卡、eSIM 套餐和话费充值共用同一套数据结构、同一个价格源和同一套下单流程。只需集成一次，Xegora 新增的每件商品都会自动为您所用。

幂等下单

创建订单和获取交付内容都支持 Idempotency-Key 请求头。无论是网络抖动、超时还是激进的重试循环——请求重放多少次都可以，订单始终只有一个。

签名 Webhook

order.processing、order.fulfilled、order.failed、order.refunded 和 wallet.credited 事件通过 HTTPS 投递，带有 HMAC-SHA256 签名（X-Xegora-Signature），采用至少一次的重试机制，并通过稳定的 X-Xegora-Event-Id 去重。

最小权限密钥

每个密钥都带有明确的权限范围集——目录读取、报价、下单、钱包读取以及资金操作权限彼此独立——并可选配 CIDR 允许列表和有效期。撤销立即生效。

预充值钱包

订单先从您的预付余额中预留资金，交付时再正式扣款；失败时自动释放预留。通过链上转账向永久充值地址充值，未使用的资金只能提现到您本人登记的收款信息。

专为选品打造的目录

按类别、国家/地区或关键词浏览，筛选固定金额或自定义金额，一次调用即可按 ID 刷新您销售的商品——每件商品都附有兑换步骤和该品牌的其他可用国家/地区，并以您的销售币种定价。

定价

批发价格，没有意外

报价即价格。其他所有商业条款均在开通商户工作区时约定。

  • 以您的销售币种计价的批发商品价格——报价总额就是从您钱包中扣除的准确金额
  • 无隐藏的按次调用费用；每个工作区统一限速为每分钟 120 次请求
  • 您的工作区方案（开通费用及条款）在商户入驻时约定
  • 未使用资金的提现报价透明——手续费、实收金额和付款日期均事先告知
申请工作区联系我们

准备好发出第一笔订单了吗？

从您的账户申请商户工作区，获批后在控制台签发限定权限范围的 API 密钥——只需三次调用，即可完成第一笔订单。完整参考文档请见 docs.xegora.com。

成为商户管理 API 密钥