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 Overview.

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)

إجمالي مبلغ الفاتورة بوحدة Micro من عملة الفاتورة

على سبيل المثال، إذا كانت قيمة 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 يمثّل دولارًا أمريكيًا واحدًا.