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

前言

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

SDK核心概念

异步操作模型

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

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

货币表示方式

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

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

产品目录管理

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

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

基础配置

初始化客户端

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: "[phone]"
};

const result = await zenditAPI.topupsPurchasesPost(fixedPurchase);

可变面额产品购买

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

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: "[e-mail]" },
    // 其他必填字段...
  ]
};

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	失败	检查错误原因

最佳实践建议

1. 幂等性处理：所有交易都应使用唯一ID，支持重试
2. 错误处理：实现全面的错误捕获和日志记录
3. 状态轮询：对于长时间交易，建议实现状态轮询机制
4. 数据验证：在提交前验证所有输入参数
5. 沙盒测试：在生产前充分使用测试环境验证

常见问题解决

1. 交易失败：检查交易状态和错误信息，确认产品是否可用
2. 余额不足：定期检查账户余额，设置自动充值
3. 参数错误：仔细阅读API文档，确保所有必填字段完整
4. 网络问题：实现适当的重试机制和超时设置

通过本指南，开发者应能够全面理解并正确使用Zendit Node SDK实现各类预付费业务的集成。建议在实际开发中结合官方文档和沙盒环境进行充分测试，确保系统稳定性和业务连续性。