Skip to main content

Documentation Index

Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt

Use this file to discover all available pages before exploring further.

オペレーター請求アカウントの財務ステータスを照会する — 支出サマリー、クレジットまたはプリペイ残高、支払いステータス、請求書履歴。予算を意識したエージェントがプロトコルを離れることなく支出判断に必要なコンテキストを得られます。 get_account_financials はセラーが get_adcp_capabilities で account_financials: true を宣言している場合のみ利用可能。オペレーター請求アカウントにのみ適用されます。エージェント請求アカウントの場合、エージェント自身の課金システムが信頼できる情報源となります。 応答時間: 約1秒。 リクエストスキーマ: /schemas/latest/account/get-account-financials-request.json レスポンススキーマ: /schemas/latest/account/get-account-financials-response.json

​
クイックスタート

キャンペーン開始前に残りのクレジットを確認します。 
import { testAgent } from "@adcp/client/testing";

const result = await testAgent.getAccountFinancials({
  account: { account_id: "acc_acme_001" },
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

if ("errors" in result.data && result.data.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(result.data.errors)}`);
}

const { spend, credit, payment_status } = result.data;
console.log(`Spent: $${spend?.total_spend} this period`);

if (credit) {
  console.log(`Available credit: $${credit.available_credit} of $${credit.credit_limit}`);
}

if (payment_status === "past_due") {
  console.log("Warning: payment is past due — campaigns may be paused");
}

​
リクエストパラメーター

パラメーター型必須説明
accountobjectYesアカウント参照 — account_id または自然キー（brand + operator + オプションの sandbox）。オペレーター請求アカウントである必要があります。
periodobjectNo支出サマリーの日付範囲: ISO 8601 日付形式の start と end。省略時は現在の請求サイクルがデフォルト。

​
レスポンス

成功レスポンス: アカウントの財務データを返します。保証されているのは account、currency、period、timezone のみ — その他はセラーが公開する内容による。
フィールド説明
accountリクエストからエコーされるアカウント参照。
currencyすべての金額の ISO 4217 通貨コード。
period実際にカバーされる期間（start、end）。請求サイクルの境界に合わせて調整される場合があります。
timezoneセラーの請求日境界の IANA タイムゾーン（例: America/New_York）。レスポンスのすべての日付はこのタイムゾーンのカレンダー日付。
spend支出サマリー: total_spend（currency 単位の金額）とオプションの media_buy_count。
creditクレジットベースアカウントに存在。credit_limit、available_credit、オプションの utilization_percent（0-100）を含みます。
balanceプリペイアカウントに存在。available 残高とオプションの last_top_up（amount、date）を含みます。
payment_statuscurrent、past_due、suspended。
payment_terms有効な支払い条件: net_15、net_30、net_45、net_60、net_90、prepay。
invoices最近の請求書の配列: invoice_id、amount、status（draft、issued、paid、past_due、void）、オプションの period、due_date、paid_date。
エラーレスポンス:
  • errors — 操作レベルのエラーの配列。財務データは含まれない。
注: レスポンスは判別共用体を使用 — 財務データまたは errors のいずれか一方のみ、両方は含まれない。

​
一般的なシナリオ

​
キャンペーン開始前の予算確認

import { testAgent } from "@adcp/client/testing";

const financials = await testAgent.getAccountFinancials({
  account: { account_id: "acc_acme_001" },
});

if (!financials.success || "errors" in financials.data) {
  throw new Error("Could not check financials");
}

const campaignBudget = 15000;
const { credit } = financials.data;

if (credit && credit.available_credit < campaignBudget) {
  console.log(
    `Insufficient credit: $${credit.available_credit} available, ` +
    `$${campaignBudget} needed. ` +
    `Credit utilization: ${credit.utilization_percent}%`
  );
} else {
  console.log("Budget check passed — proceeding with campaign");
}

​
プリペイ残高モニタリング

import { testAgent } from "@adcp/client/testing";

const financials = await testAgent.getAccountFinancials({
  account: {
    brand: { domain: "acme-corp.com" },
    operator: "acme-corp.com",
  },
});

if (!financials.success || "errors" in financials.data) {
  throw new Error("Could not check financials");
}

const { balance } = financials.data;
if (balance && balance.available < 2000) {
  console.log(
    `Low balance warning: $${balance.available} remaining. ` +
    `Consider topping up before launching new campaigns.`
  );
}

​
エラーハンドリング

エラーコード説明解決策
UNSUPPORTED_FEATUREアカウントがエージェント請求を使用している — セラーから財務データは取得できないエージェント請求アカウントには自身の課金システムを照会
UNSUPPORTED_FEATUREセラーがこのアカウントまたは期間の財務データを持っていないaccount_financials ケイパビリティが true であることを確認
ACCOUNT_NOT_FOUNDアカウントが存在しないか、アクセスできないアカウント参照を確認するか、再同期する

​
次のステップ