Method: advertisers.invoices.list

Liệt kê các hoá đơn được đăng cho một nhà quảng cáo trong một tháng nhất định.

Bạn không thể truy xuất các hoá đơn do hồ sơ thanh toán tạo ra với cấp hoá đơn là "Đối tác" thông qua phương thức này.

Yêu cầu HTTP

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

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số đường dẫn

Thông số
advertiserId

string (int64 format)

Bắt buộc. Mã của nhà quảng cáo mà bạn muốn liệt kê hoá đơn.

Tham số truy vấn

Thông số
issueMonth

string

Tháng để liệt kê hoá đơn. Nếu bạn không đặt, yêu cầu này sẽ truy xuất hoá đơn cho tháng trước.

Phải ở định dạng YYYYMM.
loiSapinInvoiceType

enum (LoiSapinInvoiceType)

Chọn loại hoá đơn cần truy xuất cho nhà quảng cáo Loi Sapin.

Chỉ áp dụng cho nhà quảng cáo Loi Sapin. Nếu không, sẽ bị bỏ qua.
pageSize

integer

Kích thước trang được yêu cầu. Phải trong khoảng từ 1 đến 200. Nếu không chỉ định, giá trị mặc định sẽ là 100. Trả về mã lỗi INVALID_ARGUMENT nếu bạn chỉ định một giá trị không hợp lệ.
pageToken

string

Mã thông báo xác định trang kết quả mà máy chủ sẽ trả về. Thông thường, đây là giá trị của nextPageToken được trả về từ lệnh gọi trước đó đến phương thức invoices.list. Nếu không được chỉ định, hệ thống sẽ trả về trang kết quả đầu tiên.

Nội dung yêu cầu

Nội dung yêu cầu phải trống.

Nội dung phản hồi

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "invoices": [
    {
      object (Invoice)
    }
  ],
  "nextPageToken": string
}
Trường
invoices[]

object (Invoice)

Danh sách hoá đơn.

Danh sách này sẽ không xuất hiện nếu trống.
nextPageToken

string

Mã thông báo để truy xuất trang kết quả tiếp theo. Truyền giá trị này trong trường pageToken trong lệnh gọi tiếp theo đến phương thức invoices.list để truy xuất trang kết quả tiếp theo.

Mã thông báo này sẽ không xuất hiện nếu không còn invoices nào để trả về.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về OAuth 2.0.

LoiSapinInvoiceType

Các loại hoá đơn có thể có cho nhà quảng cáo Loi Sapin.

Enum
LOI_SAPIN_INVOICE_TYPE_UNSPECIFIED Chưa chỉ định giá trị.
LOI_SAPIN_INVOICE_TYPE_MEDIA Hóa đơn có Chi phí truyền thông.
LOI_SAPIN_INVOICE_TYPE_PLATFORM Hoá đơn có Phí nền tảng.

Hóa đơn

Một hoá đơn.

Biểu diễn dưới dạng 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
}
Trường
name

string

Tên tài nguyên của hoá đơn.
invoiceId

string

Mã nhận dạng duy nhất của hoá đơn.
displayName

string

Tên hiển thị của hoá đơn.
paymentsProfileId

string

Mã của hồ sơ thanh toán mà hoá đơn thuộc về.

Xuất hiện trên hoá đơn PDF dưới dạng Billing ID.
paymentsAccountId

string

Mã của tài khoản thanh toán mà hoá đơn thuộc về.

Xuất hiện trên hoá đơn PDF dưới dạng Billing Account Number.
issueDate

object (Date)

Ngày phát hành hoá đơn.
dueDate

object (Date)

Ngày đến hạn của hoá đơn.
serviceDateRange

object (DateRange)

Ngày bắt đầu và ngày kết thúc dịch vụ được đề cập trong hoá đơn này.
currencyCode

string

Đơn vị tiền tệ dùng trong hoá đơn theo định dạng ISO 4217.
subtotalAmountMicros

string (int64 format)

Tổng số tiền trước thuế, tính bằng phần triệu đơn vị tiền tệ của hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 sẽ đại diện cho một đô la Mỹ.
totalTaxAmountMicros

string (int64 format)

Tổng của tất cả các khoản thuế trong hoá đơn, tính theo micro của đơn vị tiền tệ trong hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 sẽ đại diện cho một đô la Mỹ.
totalAmountMicros

string (int64 format)

Tổng số tiền trên hoá đơn, tính theo micro của đơn vị tiền tệ trên hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 sẽ đại diện cho một đô la Mỹ.
purchaseOrderNumber

string

Số đơn đặt hàng được liên kết với hoá đơn.
budgetInvoiceGroupingId

string

Mã nhóm ngân sách cho hoá đơn này.

Trường này sẽ chỉ được đặt nếu bạn đặt cấp hoá đơn của hồ sơ thanh toán tương ứng thành "Mã nhóm hoá đơn theo ngân sách".
invoiceType

enum (InvoiceType)

Loại tài liệu hoá đơn.
correctedInvoiceId

string

Mã của hoá đơn gốc được điều chỉnh bằng hoá đơn này (nếu có).

Có thể xuất hiện trên tệp PDF hoá đơn dưới dạng Reference invoice number.

Nếu bạn đặt replacedInvoiceIds, trường này sẽ trống.
replacedInvoiceIds[]

string

(Các) mã của mọi hoá đơn ban đầu đã phát hành mà hoá đơn này sẽ huỷ (nếu có). Có thể có nhiều hoá đơn được liệt kê nếu các hoá đơn đó đang được hợp nhất thành một hoá đơn.

Có thể xuất hiện trên hoá đơn PDF dưới dạng Replaced invoice numbers.

Nếu bạn đặt correctedInvoiceId, trường này sẽ trống.
pdfUrl

string

URL để tải bản sao PDF của hoá đơn xuống.

URL này dành riêng cho người dùng và yêu cầu mã truy cập OAuth 2.0 hợp lệ để truy cập. Mã truy cập phải được cung cấp trong tiêu đề HTTP Authorization: Bearer và được uỷ quyền cho một trong các phạm vi sau:

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

URL sẽ có hiệu lực trong 7 ngày sau khi truy xuất đối tượng hoá đơn này hoặc cho đến khi hoá đơn này được truy xuất lại.
budgetSummaries[]

object (BudgetSummary)

Danh sách thông tin tóm tắt cho mỗi ngân sách liên quan đến hoá đơn này.

Trường này sẽ chỉ được đặt nếu cấp chi tiết hoá đơn của hồ sơ thanh toán tương ứng được đặt thành "Đơn đặt hàng cấp ngân sách".
nonBudgetMicros

string (int64 format)

Tổng số chi phí hoặc mức điều chỉnh không liên quan đến một ngân sách cụ thể, tính theo micro theo đơn vị tiền tệ của hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 sẽ đại diện cho một đô la Mỹ.

InvoiceType

Các loại hoá đơn có thể có.

Enum
INVOICE_TYPE_UNSPECIFIED Không được chỉ định hoặc không xác định trong phiên bản này.
INVOICE_TYPE_CREDIT Hoá đơn có số tiền âm.
INVOICE_TYPE_INVOICE Hóa đơn có số tiền dương.

BudgetSummary

Thông tin tóm tắt về ngân sách của từng chiến dịch.

Biểu diễn dưới dạng JSON 
{
  "externalBudgetId": string,
  "prismaCpeCode": {
    object (PrismaCpeCode)
  },
  "preTaxAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string
}
Trường
externalBudgetId

string

Tương ứng với externalBudgetId của ngân sách chiến dịch. Nếu bạn không đặt giá trị trong ngân sách chiến dịch, thì trường này sẽ để trống.
prismaCpeCode

object (PrismaCpeCode)

Khách hàng, sản phẩm và mã ước tính có liên quan từ công cụ Mediaocean Prisma.

Chỉ áp dụng cho ngân sách chiến dịch có externalBudgetSource là EXTERNAL_BUDGET_SOURCE_MEDIA_OCEAN.
preTaxAmountMicros

string (int64 format)

Tổng số tiền phí được tính theo ngân sách này trước thuế, tính bằng phần triệu đơn vị tiền tệ của hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 sẽ đại diện cho một đô la Mỹ.
taxAmountMicros

string (int64 format)

Số tiền thuế áp dụng cho các khoản phí trong ngân sách này, tính theo micro của đơn vị tiền tệ trên hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 sẽ đại diện cho một đô la Mỹ.
totalAmountMicros

string (int64 format)

Tổng chi phí được thực hiện theo ngân sách này, bao gồm cả thuế, tính theo đơn vị tiền tệ của hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 sẽ đại diện cho một đô la Mỹ.