Method: advertisers.invoices.list

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

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

طلب HTTP

GET https://displayvideo.googleapis.com/v3/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 تمثّل دولار أمريكي واحدًا.