メインコンテンツへスキップ

インボイス

インボイス API を使用すると、インボイスの作成、管理、確定ができます。この API は、1 回限りの支払い、定期的なサブスクリプション、クレジットベースの請求など、さまざまな請求シナリオを処理するための包括的な機能を提供します。詳細なインボイス情報の取得、割引の適用、ステーキング操作の管理、履歴レコードの検索が可能です。

関連機能の詳細については、サブスクリプション および クレジットベースの請求 を参照してください。

インボイスの取得

既存のインボイスの詳細を取得します。このメソッドは、品目、適用された割引、関連するクレジット付与、支払い情報を含む包括的なインボイスオブジェクトを返します。

パラメータ

  • 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('Retrieved Invoice:', invoice.id);
    console.log('Discount Details:', invoice.discountDetails);
    console.log('Related Credit Grants:', invoice.relatedCreditGrants);
  } catch (error) {
    console.error('Error retrieving invoice:', 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) — 1ページあたりに返すアイテム数。

戻り値

  • PaginatedInvoices object — インボイスのリストとページネーション情報を含むオブジェクト。
    • list array — Invoice オブジェクトの配列。
    • count number — フィルタ条件に一致するインボイスの総数。
    • paging object — ページネーションの詳細。
      • page number — 現在のページ番号。
      • pageSize number — 1ページあたりのアイテム数。

インボイスの一覧表示

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(`Found ${invoices.count} paid invoices.`);
    invoices.list.forEach(invoice => {
      console.log(`- Invoice ID: ${invoice.id}, Amount: ${invoice.total}`);
    });
  } catch (error) {
    console.error('Error listing invoices:', error.message);
  }
}

listPaidInvoices();

インボイスの検索

インボイス番号、顧客詳細、品目説明などのさまざまなフィールドにわたって、クエリ文字列に一致するインボイスを検索します。

パラメータ

  • q string (required) — 検索クエリ文字列。
  • page number (default: 1) — ページネーションのページ番号。
  • pageSize number (default: 20) — 1ページあたりに返すアイテム数。

戻り値

  • PaginatedInvoices object — インボイスのリストとページネーション情報を含むオブジェクト。
    • list array — Invoice オブジェクトの配列。
    • count number — 検索条件に一致するインボイスの総数。
    • paging object — ページネーションの詳細。
      • page number — 現在のページ番号。
      • pageSize number — 1ページあたりのアイテム数。

インボイスの検索

javascript
import payment from '@blocklet/payment-js';

async function searchForInvoice(query) {
  try {
    const results = await payment.invoices.search({ q: query, pageSize: 5 });
    console.log(`Found ${results.count} results for query: '${query}'`);
    results.list.forEach(invoice => {
      console.log(`- Invoice ID: ${invoice.id}, Customer: ${invoice.customer.did}`);
    });
  } catch (error) {
    console.error('Error searching invoices:', 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('Invoice metadata updated:', updatedInvoice.metadata);
  } catch (error) {
    console.error('Error updating invoice:', 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(`Invoice ${voidedInvoice.id} has been voided. Status: ${voidedInvoice.status}`);
  } catch (error) {
    console.error('Error voiding invoice:', 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('Returnable Stake Information:', stakeInfo);
  } catch (error) {
    console.error('Error getting stake info:', 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(`Stake return initiated for subscription: ${result.subscriptionId}`);
    } else {
      console.error('Failed to return stake:', result.error);
    }
  } catch (error) {
    console.error('Error returning stake:', error.message);
  }
}

// 使用例:
returnStake('inv_stake_xxxxxx');