发票
发票 API 允许您创建、管理和最终确定发票。它提供了处理各种计费场景的全面功能，包括一次性支付、定期订阅和基于信用的计费。您可以检索详细的发票信息、应用折扣、管理质押操作以及搜索历史记录。
检索发票#
检索现有发票的详细信息。此方法返回一个全面的发票对象，包括订单项、应用的折扣、相关的信用授予和支付信息。
参数#
要检索的发票的唯一标识符。
返回#
一个包含扩展详细信息的 Invoice 对象。有关完整结构，请参阅 TInvoiceExpanded 和下面的附加属性。
检索发票
import payment from '@blocklet/payment-js';
async function getInvoice(invoiceId) {
try {
const invoice = await payment.invoices.retrieve(invoiceId);
console.log('检索到的发票：', invoice.id);
console.log('折扣详情：', invoice.discountDetails);
console.log('相关的信用授予：', invoice.relatedCreditGrants);
} catch (error) {
console.error('检索发票时出错：', error.message);
}
}
// 示例用法：
getInvoice('inv_xxxxxxxxxxxxxx');列出发票#
返回您的发票的分页列表。您可以根据状态、客户或订阅等各种条件筛选列表。
参数#
用于筛选的以逗号分隔的发票状态字符串（例如，paid,open）。
如果为 true，小计为零的发票将被排除。
如果为 true，与质押相关的发票将包含在结果中。
如果为 true，与返还质押相关的发票将被包含在内。
如果为 true，质押透支保护的发票将被包含在内。
如果为 true，恢复链中先前订阅的发票将被包含在内。
按自定义元数据字段筛选。将 {key} 替换为您的元数据键。
返回#
一个包含发票列表和分页信息的对象。
列出发票
import payment from '@blocklet/payment-js';
async function listPaidInvoices() {
try {
const invoices = await payment.invoices.list({
status: 'paid',
customer_id: 'cus_xxxxxxxxxxxxxx',
ignore_zero: true,
pageSize: 10,
});
console.log(`找到 ${invoices.count} 张已支付的发票。`);
invoices.list.forEach(invoice => {
console.log(`- 发票 ID: ${invoice.id}, 金额: ${invoice.total}`);
});
} catch (error) {
console.error('列出发票时出错：', error.message);
}
}
listPaidInvoices();搜索发票#
在发票编号、客户详情和订单项描述等多个字段中搜索与查询字符串匹配的发票。
参数#
搜索查询字符串。
返回#
一个包含发票列表和分页信息的对象。
搜索发票
import payment from '@blocklet/payment-js';
async function searchForInvoice(query) {
try {
const results = await payment.invoices.search({ q: query, pageSize: 5 });
console.log(`为查询“${query}”找到 ${results.count} 个结果`);
results.list.forEach(invoice => {
console.log(`- 发票 ID: ${invoice.id}, 客户: ${invoice.customer.did}`);
});
} catch (error) {
console.error('搜索发票时出错：', error.message);
}
}
// 示例用法：
searchForInvoice('Premium Plan');更新发票#
通过设置 metadata 键值对来更新指定的发票。其他发票属性通常不可更新。
参数#
要更新的发票的唯一标识符。
一组与发票对象一起存储的键值对。键最长可达 40 个字符，值最长可达 500 个字符。
返回#
更新后的 Invoice 对象。
更新发票元数据
import payment from '@blocklet/payment-js';
async function updateInvoiceMetadata(invoiceId) {
try {
const updatedInvoice = await payment.invoices.update(invoiceId, {
metadata: { order_id: 'order_12345' },
});
console.log('发票元数据已更新：', updatedInvoice.metadata);
} catch (error) {
console.error('更新发票时出错：', error.message);
}
}
// 示例用法：
updateInvoiceMetadata('inv_xxxxxxxxxxxxxx');作废发票#
作废一张发票。此操作仅适用于状态为 open 或 uncollectible 的发票。一旦作废，发票将无法支付。
参数#
要作废的发票的唯一标识符。
返回#
已作废的 Invoice 对象，其状态设置为 void。
作废发票
import payment from '@blocklet/payment-js';
async function voidInvoice(invoiceId) {
try {
const voidedInvoice = await payment.invoices.void(invoiceId);
console.log(`发票 ${voidedInvoice.id} 已作废。状态：${voidedInvoice.status}`);
} catch (error) {
console.error('作废发票时出错：', error.message);
}
}
// 示例用法：
voidInvoice('inv_xxxxxxxxxxxxxx');获取返还质押信息#
检索 stake 或 stake_overdraft_protection 发票可返还的质押金额。
参数#
质押发票的标识符。
返回#
一个包含有关剩余质押详情的对象。
获取可返还的质押
import payment from '@blocklet/payment-js';
async function getStakeInfo(invoiceId) {
try {
const stakeInfo = await payment.invoices.getReturnStake(invoiceId);
console.log('可返还的质押信息：', stakeInfo);
} catch (error) {
console.error('获取质押信息时出错：', error.message);
}
}
// 示例用法：
getStakeInfo('inv_stake_xxxxxx');返还质押#
启动与已支付的 stake 或 stake_overdraft_protection 发票关联的质押返还流程。
参数#
质押发票的标识符。
返回#
一个指示操作结果的对象。
返还质押
import payment from '@blocklet/payment-js';
async function returnStake(invoiceId) {
try {
const result = await payment.invoices.returnStake(invoiceId);
if (result.success) {
console.log(`已为订阅启动质押返还：${result.subscriptionId}`);
} else {
console.error('返还质押失败：', result.error);
}
} catch (error) {
console.error('返还质押时出错：', error.message);
}
}
// 示例用法：
returnStake('inv_stake_xxxxxx');