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.

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)

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

לדוגמה, אם 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 מייצג דולר ארה"ב אחד.