Zendit Node SDK 使用指南：全球预付费生态系统的开发集成

2025-06-01 03:40:03作者：姚月梅Lane

前言

在现代数字支付和预付费服务领域，Zendit Node SDK 为开发者提供了接入全球预付费生态系统的便捷途径。本文将深入解析该SDK的核心功能和使用方法，帮助开发者快速实现各类预付费业务的集成。

SDK核心概念

异步操作模型

Zendit Node SDK 采用完全异步的设计模式，所有API调用都返回Promise对象。开发者需要特别注意：

必须使用.then()或async/await处理异步响应
必须实现完善的错误处理机制
建议在关键业务逻辑中添加适当的等待和重试机制

货币表示方式

SDK中所有金额均采用minor currency表示（即货币的最小单位）：

美元：使用美分表示（$2.00 = 200）
其他货币同理，如CNY使用分表示（¥10.00 = 1000）

产品目录管理

Zendit平台上的产品目录具有以下特点：

产品有启用/禁用状态
禁用产品无法完成购买
开发者应定期同步目录状态
建议在前端展示时过滤掉禁用产品

基础配置

初始化客户端

import { ZenditApi } from 'zendit-sdk';

// 生产环境配置
const prodAPI = new ZenditApi('YOUR_PRODUCTION_API_KEY');

// 测试环境配置
const testAPI = new ZenditApi('YOUR_TEST_API_KEY');

最佳实践建议：

将API密钥存储在环境变量中
为不同环境创建独立的配置
实现密钥的轮换机制

账户余额查询

async function checkBalance() {
  try {
    const balance = await zenditAPI.balanceGet();
    console.log(`可用余额: ${balance.availableBalance}`);
  } catch (error) {
    console.error('查询余额失败:', error);
  }
}

eSIM功能集成

产品目录查询

eSIM产品目录支持多种查询参数：

// 基础查询
const basicOffers = await zenditAPI.esimOffersGet(10, 0);

// 带过滤条件的查询
const filteredOffers = await zenditAPI.esimOffersGet(
  10, 
  0, 
  'eSIM',   // 品牌
  'US',     // 国家代码
  'North America', // 地区
  'eSIM'    // 子类型
);

参数说明表：

参数	类型	必填	说明
limit	number	是	每页记录数(1-1024)
offset	number	是	分页偏移量
brand	string	否	运营商品牌
country	string	否	ISO 2字母国家代码
regions	string	否	地区名称
subtype	string	否	产品子类型

eSIM购买流程

完整的eSIM购买流程示例：

async function purchaseESim() {
  // 1. 查询产品详情
  const offer = await zenditAPI.esimOffersOfferIdGet('ESIM-US-7D-1GB');
  
  // 2. 创建购买请求
  const purchaseData = {
    transactionId: generateUniqueId(), // 建议使用UUID v4
    offerId: 'ESIM-US-7D-1GB'
  };
  
  // 3. 提交购买
  const result = await zenditAPI.esimPurchasesPost(purchaseData);
  
  // 4. 获取QR码
  const qrCode = await zenditAPI.esimPurchasesTransactionIdQrcodeGet(
    result.transactionId,
    'json' // 可选'blob'或'json'
  );
  
  return qrCode;
}

移动充值功能集成

固定面额产品购买

const fixedPurchase = {
  transactionId: uuid.v4(),
  offerId: "CUBACEL_CU_PAQUETE001",
  recipientPhoneNumber: "+5355564362"
};

const result = await zenditAPI.topupsPurchasesPost(fixedPurchase);

可变面额产品购买

const rangePurchase = {
  transactionId: uuid.v4(),
  offerId: "CUBACEL_CU_OPEN",
  recipientPhoneNumber: "+5355564362",
  value: {
    type: 'ZEND', // 也可以是'COST'或'PRICE'
    value: 25000  // 根据type不同代表不同含义
  },
  sender: {
    phoneNumber: "+15515551212"
  }
};

const result = await zenditAPI.topupsPurchasesPost(rangePurchase);

数字礼品卡集成

带额外字段的购买

const voucherData = {
  transactionId: uuid.v4(),
  offerId: "AIRCANADA_CA_001_EGIFT_USD",
  fields: [
    { key: "recipient.firstName", value: "张" },
    { key: "recipient.lastName", value: "三" },
    { key: "recipient.email", value: "zhangsan@example.com" },
    // 其他必填字段...
  ]
};

const result = await zenditAPI.vouchersPurchasesPost(voucherData);

交易查询与管理

通用交易查询

// 查询单个交易
const transaction = await zenditAPI.transactionsTransactionIdGet('txn-123');

// 分页查询交易列表
const transactions = await zenditAPI.transactionsGet(
  10, // limit
  0,  // offset
  'gte2023-03-29T00:00:00Z', // 创建时间筛选
  'TOPUP' // 产品类型筛选
);

交易状态说明

状态	含义	处理建议
ACCEPTED	交易已接收	等待进一步状态更新
PENDING	处理中	正常等待
AUTHORIZED	已授权	资金已预留
IN_PROGRESS	履行中	供应商处理中
DONE	完成	业务成功
FAIL	失败	检查错误原因