跳到主要内容

发票

发票 API 允许您创建、管理和最终确定发票。它提供了处理各种计费场景的全面功能，包括一次性支付、定期订阅和基于信用的计费。您可以检索详细的发票信息、应用折扣、管理质押操作以及搜索历史记录。

有关相关功能的更多信息，请参阅订阅和基于信用的计费。

检索发票

检索现有发票的详细信息。此方法返回一个全面的发票对象，包括订单项、应用的折扣、相关的信用授予和支付信息。

参数

  • id string (required) — 要检索的发票的唯一标识符。

返回

  • Invoice object — 一个包含扩展详细信息的 Invoice 对象。有关完整结构，请参阅 TInvoiceExpanded 和下面的附加属性。
    • discountDetails array — 应用于发票的折扣详情。
      • coupon object — 与折扣关联的优惠券。
      • promotionCode object — 用于应用折扣的促销代码。
    • relatedInvoice object — 相关发票的信息（如果适用，例如贷项通知单）。
    • relatedCreditGrants array — 由于此发票已支付而创建的信用授予列表。
    • paymentLink object — 用于创建此发票结账会话的支付链接。
    • checkoutSession object — 与此发票关联的结账会话。

检索发票

javascript
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');

列出发票

返回您的发票的分页列表。您可以根据状态、客户或订阅等各种条件筛选列表。

参数

  • status string — 用于筛选的以逗号分隔的发票状态字符串（例如，paid,open）。
  • customer_id string — 按特定客户 ID 筛选发票。
  • customer_did string — 按客户的 DID 筛选发票。
  • subscription_id string — 按特定订阅 ID 筛选发票。
  • currency_id string — 按特定货币 ID 筛选发票。
  • ignore_zero boolean (default: false) — 如果为 true，小计为零的发票将被排除。
  • include_staking boolean (default: false) — 如果为 true，与质押相关的发票将包含在结果中。
  • include_return_staking boolean (default: false) — 如果为 true，与返还质押相关的发票将被包含在内。
  • include_overdraft_protection boolean (default: true) — 如果为 true，质押透支保护的发票将被包含在内。
  • include_recovered_from boolean (default: false) — 如果为 true，恢复链中先前订阅的发票将被包含在内。
  • metadata.{key} string — 按自定义元数据字段筛选。将 {key} 替换为您的元数据键。
  • page number (default: 1) — 分页的页码。
  • pageSize number (default: 20) — 每页返回的项目数。

返回

  • PaginatedInvoices object — 一个包含发票列表和分页信息的对象。
    • list array — Invoice 对象数组。
    • count number — 符合筛选条件的发票总数。
    • paging object — 分页详情。
      • page number — 当前页码。
      • pageSize number — 每页的项目数。

列出发票

javascript
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();

搜索发票

在发票编号、客户详情和订单项描述等多个字段中搜索与查询字符串匹配的发票。

参数

  • q string (required) — 搜索查询字符串。
  • page number (default: 1) — 分页的页码。
  • pageSize number (default: 20) — 每页返回的项目数。

返回

  • PaginatedInvoices object — 一个包含发票列表和分页信息的对象。
    • list array — Invoice 对象数组。
    • count number — 符合搜索条件的发票总数。
    • paging object — 分页详情。
      • page number — 当前页码。
      • pageSize number — 每页的项目数。

搜索发票

javascript
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 键值对来更新指定的发票。其他发票属性通常不可更新。

参数

  • id string (required) — 要更新的发票的唯一标识符。
  • metadata object — 一组与发票对象一起存储的键值对。键最长可达 40 个字符，值最长可达 500 个字符。

返回

  • Invoice object — 更新后的 Invoice 对象。

更新发票元数据

javascript
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 的发票。一旦作废，发票将无法支付。

参数

  • id string (required) — 要作废的发票的唯一标识符。

返回

  • Invoice object — 已作废的 Invoice 对象，其状态设置为 void。

作废发票

javascript
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 发票可返还的质押金额。

参数

  • id string (required) — 质押发票的标识符。

返回

  • StakeInfo object — 一个包含有关剩余质押详情的对象。

获取可返还的质押

javascript
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 发票关联的质押返还流程。

参数

  • id string (required) — 质押发票的标识符。

返回

  • ReturnResult object — 一个指示操作结果的对象。
    • success boolean — 指示返还质押流程是否成功启动。
    • subscriptionId string — 关联订阅的 ID。
    • error string — 如果操作失败，则显示错误消息。

返还质押

javascript
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');