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)

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

لا ينطبق ذلك إلا على المعلِنين الخاضعين لقانون 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.

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. يجب تقديم رمز التفويض في عنوان Authorization: Bearer HTTP وأن يكون مفوَّضًا لأحد النطاقات التالية:

  • 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 يمثّل دولار أمريكي واحد.