Method: advertisers.invoices.list

רשימה של החשבוניות שפורסמו עבור מפרסם מסוים בחודש נתון.

אי אפשר לאחזר חשבוניות שנוצרו על ידי פרופילי חיוב ברמת חשבונית 'שותף' באמצעות השיטה הזו.

בקשת HTTP

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

כתובת ה-URL משתמשת בתחביר של Transcoding של gRPC.

פרמטרים של נתיב

פרמטרים
advertiserId

string (int64 format)

חובה. המזהה של המפרסם שרוצים להציג את החשבוניות שלו.

פרמטרים של שאילתה

פרמטרים
issueMonth

string

החודש שבו רוצים להציג את החשבוניות. אם לא תגדירו את השדה, הבקשה תשחזר חשבוניות מהחודש הקודם.

הפורמט הנכון הוא YYYYMM.
loiSapinInvoiceType

enum (LoiSapinInvoiceType)

בחירת סוג החשבונית לאחזור עבור מפרסמים בכפוף ל-Loi Sapin.

רלוונטי רק למפרסמים בכפוף ל-Loi Sapin. אחרת, המערכת תתעלם מהם.
pageSize

integer

גודל הדף המבוקש. חייב להיות בין 1 לבין 200. אם לא צוין ערך, ברירת המחדל תהיה 100. הפונקציה מחזירה את קוד השגיאה INVALID_ARGUMENT אם צוין ערך לא חוקי.
pageToken

string

אסימון שמזהה דף תוצאות שהשרת אמור להציג. בדרך כלל, זהו הערך של nextPageToken שהוחזר מהקריאה הקודמת לשיטה invoices.list. אם לא מצוין, יוצג דף התוצאות הראשון.

גוף הבקשה

גוף הבקשה חייב להיות ריק.

גוף התשובה

אם הפעולה מצליחה, גוף התגובה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "invoices": [
    {
      object (Invoice)
    }
  ],
  "nextPageToken": string
}
שדות
invoices[]

object (Invoice)

רשימת החשבוניות.

אם הרשימה הזו ריקה, היא לא תופיע.
nextPageToken

string

אסימון לאחזור של דף התוצאות הבא. כדי לאחזר את דף התוצאות הבא, מעבירים את הערך הזה בשדה pageToken בקריאה הבאה לשיטה invoices.list.

האסימון הזה לא יופיע אם אין יותר invoices להחזיר.

היקפי הרשאה

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

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

מידע נוסף זמין בOAuth 2.0 Overview.

LoiSapinInvoiceType

סוגי החשבוניות האפשריים למפרסמים בכפוף ל-Loi Sapin.

טיפוסים בני מנייה (enum)
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

המזהה הייחודי של החשבונית.
displayName

string

השם המוצג של החשבונית.
paymentsProfileId

string

המזהה של פרופיל התשלומים שאליו שייכת החשבונית.

מופיע בקובץ ה-PDF של החשבונית כ-Billing ID.
paymentsAccountId

string

המזהה של חשבון התשלומים שאליו שייכת החשבונית.

מופיע בקובץ ה-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)

סך כל המיסים בחשבונית, ב-micros של המטבע של החשבונית.

לדוגמה, אם הערך של currencyCode הוא USD, הערך 1000000 מייצג דולר ארה"ב אחד.
totalAmountMicros

string (int64 format)

הסכום הכולל של החשבונית, ב-micros של המטבע של החשבונית.

לדוגמה, אם הערך של currencyCode הוא USD, הערך 1000000 מייצג דולר ארה"ב אחד.
purchaseOrderNumber

string

מספר הזמנת הרכש שמשויך לחשבונית.
budgetInvoiceGroupingId

string

מזהה קיבוץ התקציב של החשבונית הזו.

השדה הזה יוגדר רק אם ברמת החשבונית של פרופיל החיוב התואם הוגדר 'מזהה קיבוץ של חשבוניות תקציב'.
invoiceType

enum (InvoiceType)

סוג מסמך החשבונית.
correctedInvoiceId

string

המזהה של החשבונית המקורית שמבוצעת בה התאמה באמצעות החשבונית הזו, אם רלוונטי.

יכול להיות שיופיע בקובץ ה-PDF של החשבונית כ-Reference invoice number.

אם השדה replacedInvoiceIds מוגדר, השדה הזה יהיה ריק.
replacedInvoiceIds[]

string

המזהים של כל חשבונית שהונפקה במקור וזו מבוטלת על ידי החשבונית הזו, אם רלוונטי. יכול להיות שיופיעו כמה חשבוניות אם החשבוניות האלה מקובצות לחשבונית אחת.

יכול להיות שיופיע בקובץ ה-PDF של החשבונית כ-Replaced invoice numbers.

אם השדה correctedInvoiceId מוגדר, השדה הזה יהיה ריק.
pdfUrl

string

כתובת ה-URL להורדת עותק PDF של החשבונית.

כתובת ה-URL הזו ספציפית למשתמש, וצריך אסימון גישה תקף מסוג OAuth 2.0 כדי לגשת אליה. אסימון הגישה צריך להופיע בכותרת HTTP מסוג Authorization: Bearer, עם הרשאה לאחד מההיקפים הבאים:

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

כתובת ה-URL תהיה תקפה למשך 7 ימים לאחר אחזור אובייקט החשבונית הזה, או עד שהחשבונית תוחזר שוב.
budgetSummaries[]

object (BudgetSummary)

רשימה של סיכום המידע לגבי כל תקציב שמשויך לחשבונית הזו.

השדה הזה יוגדר רק אם רמת פרטי החשבונית בפרופיל החיוב התואם הוגדרה כ'הזמנה ברמת התקציב'.
nonBudgetMicros

string (int64 format)

הסכום הכולל של העלויות או ההתאמות שלא קשורות לתקציב מסוים, ב-micros של המטבע של החשבונית.

לדוגמה, אם הערך של currencyCode הוא USD, הערך 1000000 מייצג דולר ארה"ב אחד.

InvoiceType

סוגי החשבוניות האפשריים.

טיפוסים בני מנייה (enum)
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)

קודי לקוח, מוצר והצעת מחיר רלוונטיים מהכלי Prisma של Mediaocean.

ההגדרה רלוונטית רק לתקציבים של קמפיינים עם הערך EXTERNAL_BUDGET_SOURCE_MEDIA_OCEAN ב-externalBudgetSource.
preTaxAmountMicros

string (int64 format)

סכום החיובים שבוצעו במסגרת התקציב הזה לפני מיסים, ב-micros של מטבע החשבונית.

לדוגמה, אם הערך של currencyCode הוא USD, הערך 1000000 מייצג דולר ארה"ב אחד.
taxAmountMicros

string (int64 format)

סכום המס שחלה על החיובים במסגרת התקציב הזה, ב-micros של המטבע של החשבונית.

לדוגמה, אם הערך של currencyCode הוא USD, הערך 1000000 מייצג דולר ארה"ב אחד.
totalAmountMicros

string (int64 format)

הסכום הכולל של החיובים שבוצעו במסגרת התקציב הזה, כולל מס, במיליוני חלקים של המטבע של החשבונית.

לדוגמה, אם הערך של currencyCode הוא USD, הערך 1000000 מייצג דולר ארה"ב אחד.