Method: advertisers.invoices.list

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

Bạn không thể truy xuất hoá đơn do hồ sơ thanh toán có cấp hoá đơn là "Đối tác" tạo ra bằng 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ã nhận dạng của nhà quảng cáo để 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 không được đặt, yêu cầu 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ững nhà quảng cáo tuân thủ luật Loi Sapin. Nếu không, tham số này sẽ bị bỏ qua.
pageSize

integer

Kích thước trang được yêu cầu. Phải nằm trong khoảng từ 1 đến 200. Nếu bạn 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 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 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 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 vào 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 OAuth 2.0 Overview.

LoiSapinInvoiceType

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

Enum
LOI_SAPIN_INVOICE_TYPE_UNSPECIFIED Bạn chưa chỉ định giá trị.
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 duy nhất.

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 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ệ được dùng trong hoá đơn ở định dạng ISO 4217.
subtotalAmountMicros

string (int64 format)

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

Ví dụ: nếu currencyCode là USD, thì 1000000 biểu thị 1 đô la Mỹ.
totalTaxAmountMicros

string (int64 format)

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

Ví dụ: nếu currencyCode là USD, thì 1000000 biểu thị 1 đô la Mỹ.
totalAmountMicros

string (int64 format)

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

Ví dụ: nếu currencyCode là USD, thì 1000000 biểu thị 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 cấp hoá đơn của hồ sơ thanh toán tương ứng được đặt thành "Mã nhóm hoá đơn theo ngân sách".
invoiceType

enum (InvoiceType)

Loại chứng từ hoá đơn.
correctedInvoiceId

string

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

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

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

string

Mã của (các) hoá đơn được phát hành ban đầu và đang bị hoá đơn này huỷ (nếu có). Bạn có thể thấy nhiều hoá đơn nếu những hoá đơn đó đang được hợp nhất thành một hoá đơn duy nhất.

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

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

string

URL để tải bản sao hoá đơn ở định dạng PDF xuống.

URL này dành riêng cho người dùng và cần có 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 này 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 từng ngân sách liên kết với 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ố tiền 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 bằng đơn vị micro của đơn vị tiền tệ trên hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 biểu thị 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ị trong ngân sách chiến dịch, thì trường này sẽ trống.
prismaCpeCode

object (PrismaCpeCode)

Mã khách hàng, sản phẩm và mã ước tính có liên quan trong 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 tính theo ngân sách này trước thuế, tính bằng phần triệu của đơn vị tiền tệ trên hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 biểu thị 1 đô 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 bằng micro của đơn vị tiền tệ trong hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 biểu thị 1 đô la Mỹ.
totalAmountMicros

string (int64 format)

Tổng số tiền phí được tính theo ngân sách này, bao gồm cả thuế, tính bằng đơn vị vi mô của đơn vị tiền tệ trong hoá đơn.

Ví dụ: nếu currencyCode là USD, thì 1000000 biểu thị 1 đô la Mỹ.