Method: advertisers.invoices.list

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

Hoá đơn được tạo bởi các hồ sơ thanh toán có "Đối tác" không thể truy xuất cấp hoá đơn thông qua phương pháp này.

Yêu cầu HTTP

GET https://displayvideo.googleapis.com/v2/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ã nhận dạng của nhà quảng cáo cần liệt kê hoá đơn.

Tham số truy vấn

Thông số
issueMonth

string

Tháng cần liệt kê hoá đơn. Nếu bạn không đặt chính sách này, yêu cầu sẽ truy xuất hoá đơn của 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 bạn không chỉ định thì chế độ mặc định sẽ là 100. Trả về mã lỗi INVALID_ARGUMENT nếu chỉ định một giá trị không hợp lệ.

pageToken

string

Mã thông báo xác định một 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, trang kết quả đầu tiên sẽ được trả về.

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 có 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 vào trường pageToken trong lệnh gọi tiếp theo tới 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 có nếu không còn invoices để 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 Giá trị chưa được chỉ định.
LOI_SAPIN_INVOICE_TYPE_MEDIA Hoá đơ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ã hồ sơ thanh toán chứa hoá đơn.

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

paymentsAccountId

string

Mã của tài khoản thanh toán chứa hoá đơn.

Xuất hiện trên hoá đơn PDF dưới tên 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 quy định trong hóa đơn này.

currencyCode

string

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

subtotalAmountMicros

string (int64 format)

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

Ví dụ: nếu currencyCodeUSD, thì 1000000 tương ứng với 1 đô la Mỹ.

totalTaxAmountMicros

string (int64 format)

Tổng tất cả các khoản thuế trong hoá đơn, tính bằng đơn vị tiền tệ trên hoá đơn.

Ví dụ: nếu currencyCodeUSD, thì 1000000 tương ứng với 1 đô la Mỹ.

totalAmountMicros

string (int64 format)

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

Ví dụ: nếu currencyCodeUSD, thì 1000000 tương ứng với 1 đô la Mỹ.

purchaseOrderNumber

string

Số đơn đặt hàng 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 chứng từ hóa đơn.

correctedInvoiceId

string

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

Có thể xuất hiện trên bản PDF của hoá đơn dưới tên Reference invoice number.

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

replacedInvoiceIds[]

string

(Các) mã của bất kỳ hóa đơn phát hành ban đầu nào đang bị hủy bởi hóa đơn này, nếu có. Nhiều hoá đơn có thể được liệt kê nếu những hoá đơn đó được hợp nhất thành một hoá đơn duy nhất.

Có thể xuất hiện trên hoá đơn ở dạng 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. Bạn phải cung cấp mã truy 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 thiết lập nếu bạn đặt cấp thông tin hoá đơn của hồ sơ thanh toán tương ứng thành "Đơn đặt hàng theo mức ngân sách".

nonBudgetMicros

string (int64 format)

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

Ví dụ: nếu currencyCodeUSD, thì 1000000 tương ứng với 1 đô 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 Hoá đơ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ị này 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ó externalBudgetSourceEXTERNAL_BUDGET_SOURCE_MEDIA_OCEAN.

preTaxAmountMicros

string (int64 format)

Tổng chi phí được thực hiện theo ngân sách này trước thuế, tính bằng đơn vị tiền tệ trên hoá đơn.

Ví dụ: nếu currencyCodeUSD, thì 1000000 tương ứng với 1 đô la Mỹ.

taxAmountMicros

string (int64 format)

Số tiền thuế được áp dụng cho các khoản phí trong ngân sách này, tính bằng đơn vị tiền tệ của hóa đơn.

Ví dụ: nếu currencyCodeUSD, thì 1000000 tương ứng với 1 đô la Mỹ.

totalAmountMicros

string (int64 format)

Tổng số 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 currencyCodeUSD, thì 1000000 tương ứng với 1 đô la Mỹ.