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

LoiSapinInvoiceType

أنواع الفواتير المحتمَلة للمعلِنين الخاضعين لقانون Sapin

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