Method: advertisers.invoices.list

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

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

طلب HTTP

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