Method: advertisers.invoices.list

列出廣告主在指定月份發布的月結單。

如果月結單是由月結單層級為「合作夥伴」的帳單資料產生，則無法透過這個方法擷取。

HTTP 要求

GET https://displayvideo.googleapis.com/v5/advertisers/{advertiserId}/invoices

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
advertiserId

string (int64 format)

必填。要列出月結單的廣告主 ID。

查詢參數

參數
issueMonth

string

要列出月結單的月份。如未設定，要求會擷取上個月的月結單。

格式必須為 YYYYMM。
loiSapinInvoiceType

enum (LoiSapinInvoiceType)

選取要為 Loi Sapin 廣告主擷取的月結單類型。

僅適用於 Loi Sapin 廣告主。否則會遭到忽略。
pageSize

integer

要求的頁面大小。必須介於 1 至 200 之間。如未指定，則預設為 100。如果指定的值無效，則會傳回錯誤代碼 INVALID_ARGUMENT。
pageToken

string

用來識別伺服器應傳回哪一頁結果的權杖。通常，這是先前呼叫 invoices.list 方法時傳回的 nextPageToken 值。如未指定，系統會傳回第一頁的結果。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "invoices": [
    {
      object (Invoice)
    }
  ],
  "nextPageToken": string
}
欄位
invoices[]

object (Invoice)

應付憑據清單。

如果清單空白，就不會顯示。
nextPageToken

string

用來擷取下一頁結果的權杖。在後續呼叫 invoices.list 方法時，將這個值傳遞至 pageToken 欄位，即可擷取下一頁結果。

如果沒有更多 invoices 可傳回，就不會顯示這個權杖。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/display-video
  • https://www.googleapis.com/auth/display-video-mediaplanning

詳情請參閱OAuth 2.0 Overview。

LoiSapinInvoiceType

Loi Sapin 廣告主可能收到的月結單類型。

列舉
LOI_SAPIN_INVOICE_TYPE_UNSPECIFIED 未指定值。
LOI_SAPIN_INVOICE_TYPE_MEDIA 含媒體費用的月結單。
LOI_SAPIN_INVOICE_TYPE_PLATFORM 含平台費用的月結單。

應付憑據

單一月結單。

JSON 表示法 
{
  "name": string,
  "invoiceId": string,
  "displayName": string,
  "paymentsProfileId": string,
  "paymentsAccountId": string,
  "issueDate": {
    object (Date)
  },
  "dueDate": {
    object (Date)
  },
  "serviceDateRange": {
    object (DateRange)
  },
  "currencyCode": string,
  "subtotalAmountMicros": string,
  "totalTaxAmountMicros": string,
  "totalAmountMicros": string,
  "purchaseOrderNumber": string,
  "budgetInvoiceGroupingId": string,
  "invoiceType": enum (InvoiceType),
  "correctedInvoiceId": string,
  "replacedInvoiceIds": [
    string
  ],
  "pdfUrl": string,
  "budgetSummaries": [
    {
      object (BudgetSummary)
    }
  ],
  "nonBudgetMicros": string
}
欄位
name

string

應付憑據的資源名稱。
invoiceId

string

應付憑據的專屬 ID。
displayName

string

月結單的顯示名稱。
paymentsProfileId

string

月結單所屬付款資料的 ID。

在月結單 PDF 中顯示為 Billing ID。
paymentsAccountId

string

月結單所屬付款帳戶的 ID。

在月結單 PDF 中顯示為 Billing Account Number。
issueDate

object (Date)

應付憑據開立日期。
dueDate

object (Date)

月結單到期日。
serviceDateRange

object (DateRange)

這份月結單涵蓋的服務開始和結束日期。
currencyCode

string

月結單使用的貨幣，採用 ISO 4217 格式。
subtotalAmountMicros

string (int64 format)

稅前小計金額，以月結單幣別的百萬分之一為單位。

舉例來說，如果 currencyCode 為 USD，則 1000000 代表 1 美元。
totalTaxAmountMicros

string (int64 format)

月結單中所有稅金的總和，以月結單幣別的百萬分之一為單位。

舉例來說，如果 currencyCode 為 USD，則 1000000 代表 1 美元。
totalAmountMicros

string (int64 format)

應付憑據總金額，以應付憑據幣別的百萬分之一為單位。

舉例來說，如果 currencyCode 為 USD，則 1000000 代表 1 美元。
purchaseOrderNumber

string

與月結單相關聯的訂購單號碼。
budgetInvoiceGroupingId

string

這份月結單的預算分組 ID。

只有在相應帳單資料的月結單層級設為「預算月結單分組 ID」時，系統才會設定這個欄位。
invoiceType

enum (InvoiceType)

應付憑據文件的類型。
correctedInvoiceId

string

這張月結單調整的原始月結單 ID (如有)。

在月結單 PDF 上可能顯示為 Reference invoice number。

如果已設定 replacedInvoiceIds，這個欄位會留空。
replacedInvoiceIds[]

string

原先開立且由這張月結單取消的月結單 ID(如有)。如果多張月結單合併為一張，則可能會列出多張月結單。

在月結單 PDF 中可能顯示為 Replaced invoice numbers。

如果已設定 correctedInvoiceId，這個欄位會留空。
pdfUrl

string

下載月結單 PDF 副本的網址。

這個網址因使用者而異，必須有有效的 OAuth 2.0 存取權杖才能存取。存取權杖必須在 Authorization: Bearer HTTP 標頭中提供，並獲得下列其中一個範圍的授權：

  • https://www.googleapis.com/auth/display-video-mediaplanning
  • https://www.googleapis.com/auth/display-video

網址的有效期限為 7 天 (從擷取這個月結單物件起算)，或直到再次擷取這個月結單為止。
budgetSummaries[]

object (BudgetSummary)

與這張月結單相關聯的各項預算摘要資訊清單。

只有在相應帳單資料的月結單詳細資料層級設為「預算層級訂購單」時，系統才會設定這個欄位。
nonBudgetMicros

string (int64 format)

未與特定預算連結的費用或調整項總金額，以百萬分之一為單位，幣別與月結單相同。

舉例來說，如果 currencyCode 為 USD，則 1000000 代表 1 美元。

InvoiceType

可能的月結單類型。

列舉
INVOICE_TYPE_UNSPECIFIED 未指定或在這個版本中不明。
INVOICE_TYPE_CREDIT 月結單金額為負數。
INVOICE_TYPE_INVOICE 月結單金額為正數。

BudgetSummary

個別廣告活動預算的摘要資訊。

JSON 表示法 
{
  "externalBudgetId": string,
  "prismaCpeCode": {
    object (PrismaCpeCode)
  },
  "preTaxAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string
}
欄位
externalBudgetId

string

對應廣告活動預算的 externalBudgetId。如果未在廣告活動預算中設定值，這個欄位會留空。
prismaCpeCode

object (PrismaCpeCode)

Mediaocean Prisma 工具中的相關客戶、產品和預估代碼。

僅適用於 externalBudgetSource 為 EXTERNAL_BUDGET_SOURCE_MEDIA_OCEAN 的廣告活動預算。
preTaxAmountMicros

string (int64 format)

這筆預算產生的稅前費用總和，以月結單幣別的百萬分之一為單位。

舉例來說，如果 currencyCode 為 USD，則 1000000 代表 1 美元。
taxAmountMicros

string (int64 format)

這筆預算費用適用的稅額，以月結單幣別的百萬分之一為單位。

舉例來說，如果 currencyCode 為 USD，則 1000000 代表 1 美元。
totalAmountMicros

string (int64 format)

這筆預算產生的總費用 (含稅)，以月結單幣別的百萬分之一為單位。

舉例來說，如果 currencyCode 為 USD，則 1000000 代表 1 美元。