Method: advertisers.invoices.list

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

由帳單資料產生「合作夥伴」的月結單應付憑據層級無法擷取。

HTTP 要求

GET https://displayvideo.googleapis.com/v2/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 總覽。

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 代表一美元。
totalTaxAmountMicros

string (int64 format)

月結單中所有稅金的總和，以月結單貨幣的百萬分之一表示。

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

string (int64 format)

月結單總金額 (以月結單貨幣的百萬分之一表示)。

舉例來說，如果 currencyCode 是 USD，則 1000000 代表一美元。
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 代表一美元。

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 代表一美元。
taxAmountMicros

string (int64 format)

這筆預算中應繳納的稅金金額，以月結單幣別的百萬分之一表示。

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

string (int64 format)

計入這筆預算的費用總額 (包括稅金)，以應付憑據貨幣的百萬分之一為單位。

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