跳到主要內容

發票

發票 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(`找到 ${results.count} 個符合查詢 '${query}' 的結果`);
    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');