Method: advertisers.invoices.list

列出廣告主在特定月份的月結單。

使用帳單資料產生的月結單層級為「Partner」，無法透過這個方法擷取。

HTTP 要求

GET https://displayvideo.googleapis.com/v4/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 美元。