Method: advertisers.invoices.list

列出特定月份為廣告主發布的月結單。

如果帳單設定檔的月結單層級為「合作夥伴」，則無法透過這個方法擷取月結單。

HTTP 要求

GET https://displayvideo.googleapis.com/v3/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 代表一美元。
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 代表一美元。