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 美元。