Method: advertisers.invoices.list

يسرد الفواتير التي تمّ نشرها لأحد المعلِنين في شهر معيّن.

لا يمكن استرداد الفواتير التي تم إنشاؤها من خلال الملفات الشخصية للفوترة على مستوى فاتورة "شريك" من خلال هذه الطريقة.

طلب HTTP

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

يستخدم عنوان URL بنية تحويل الترميز gRPC.

معلمات المسار

المَعلمات
advertiserId

string (int64 format)

مطلوبة. رقم تعريف المعلِن المطلوب إدراج فواتير له.

معلمات طلب البحث

المَعلمات
issueMonth

string

الشهر الذي سيتم إدراج فواتير له. وإذا لم يتم ضبط السياسة، سيسترد الطلب الفواتير الخاصة بالشهر السابق.

يجب استخدام التنسيق YYYYMM.
loiSapinInvoiceType

enum (LoiSapinInvoiceType)

اختَر نوع الفاتورة المطلوب استردادها للمعلِنين الذين يخضعون لقانون سابين.

ينطبق فقط على المعلنين الذين يخضعون لقانون سابين. وسيتم تجاهلها في أي وقت آخر.
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_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)

المبلغ الإجمالي للفاتورة بالميكرو لعملة الفاتورة.

على سبيل المثال، إذا كانت قيمة 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)

المبلغ الإجمالي للتكاليف أو التسويات غير المرتبط بميزانية معيّنة، بالمايكرو من عملة الفاتورة.

على سبيل المثال، إذا كانت قيمة currencyCode هي USD، ستمثِّل 1000000 دولار أمريكي واحد.

InvoiceType

أنواع الفواتير المحتملة.

عمليات التعداد
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، ستمثِّل 1000000 دولار أمريكي واحد.
taxAmountMicros

string (int64 format)

مبلغ الضريبة المطبَّقة على الرسوم التي يتم تحصيلها بموجب هذه الميزانية، بالميكرو ثانية من عملة الفاتورة

على سبيل المثال، إذا كانت قيمة currencyCode هي USD، ستمثِّل 1000000 دولار أمريكي واحد.
totalAmountMicros

string (int64 format)

مجموع الرسوم المحصّلة بموجب هذه الميزانية، بما في ذلك الضريبة، بالمايكرو من عملة الفاتورة.

على سبيل المثال، إذا كانت قيمة currencyCode هي USD، ستمثِّل 1000000 دولار أمريكي واحد.