Method: advertisers.invoices.list

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

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

בקשת HTTP

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

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

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

פרמטרים
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, המשמעות היא ש-1,000,000 מייצג דולר ארה"ב אחד.
totalTaxAmountMicros

string (int64 format)

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

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

string (int64 format)

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

לדוגמה, אם הערך של currencyCode הוא USD, המשמעות היא ש-1,000,000 מייצג דולר ארה"ב אחד.
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)

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

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

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)

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

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

string (int64 format)

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

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

string (int64 format)

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

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

string (int64 format)

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

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