Method: customers.invoices.list

عرض جميع الفواتير المرتبطة بإعدادات الفوترة لشهر معيّن

قائمة الأخطاء الملموسة: AuthenticationError AuthorizationError FieldError HeaderError InternalError InvoiceError QuotaError RequestError

طلب HTTP

GET https://googleads.googleapis.com/v16/customers/{customerId}/invoices

يستخدم عنوان URL بنية تحويل الترميز gRPC.

معلمات المسار

المَعلمات
customerId

string

مطلوبة. رقم تعريف العميل المطلوب جلب الفواتير له.

معلمات طلب البحث

المَعلمات
billingSetup

string

مطلوبة. اسم مورد إعداد الفوترة الخاص بالفواتير المطلوبة

customers/{customerId}/billingSetups/{billing_setup_id}
issueYear

string

مطلوبة. تعرض هذه السمة سنة الإصدار المطلوب استرداد الفواتير بالتنسيق yyyy. يمكن استرداد الفواتير التي تم إصدارها في عام 2019 أو بعد ذلك فقط.
issueMonth

enum (MonthOfYear)

مطلوبة. شهر الإصدار لاسترداد الفواتير.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

رسالة الرد لـ "InvoiceService.ListInvoices".

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "invoices": [
    {
      object (Invoice)
    }
  ]
}
الحقول
invoices[]

object (Invoice)

قائمة الفواتير التي تتطابق مع إعدادات الفوترة والفترة الزمنية

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/adwords

لمزيد من المعلومات، راجِع نظرة عامة على بروتوكول OAuth 2.0.

فاتورة

فاتورة. يتم عرض جميع معلومات الفاتورة لتتطابق مع الفاتورة بتنسيق PDF. بالنسبة إلى الفواتير التي مرّ عليها أكثر من إطلاق InvoiceService، قد لا تتطابق المعلومات المعروضة في النبذة مع الفاتورة بتنسيق PDF.

تمثيل JSON 
{
  "resourceName": string,
  "type": enum (InvoiceType),
  "serviceDateRange": {
    object (DateRange)
  },
  "adjustmentsSubtotalAmountMicros": string,
  "adjustmentsTaxAmountMicros": string,
  "adjustmentsTotalAmountMicros": string,
  "regulatoryCostsSubtotalAmountMicros": string,
  "regulatoryCostsTaxAmountMicros": string,
  "regulatoryCostsTotalAmountMicros": string,
  "replacedInvoices": [
    string
  ],
  "accountBudgetSummaries": [
    {
      object (AccountBudgetSummary)
    }
  ],
  "accountSummaries": [
    {
      object (AccountSummary)
    }
  ],
  "id": string,
  "billingSetup": string,
  "paymentsAccountId": string,
  "paymentsProfileId": string,
  "issueDate": string,
  "dueDate": string,
  "currencyCode": string,
  "exportChargeSubtotalAmountMicros": string,
  "exportChargeTaxAmountMicros": string,
  "exportChargeTotalAmountMicros": string,
  "subtotalAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string,
  "correctedInvoice": string,
  "pdfUrl": string
}
الحقول
resourceName

string

النتائج فقط. اسم مورد الفاتورة يمكن لعدة عملاء مشاركة فاتورة معيّنة، لذا قد تشير أسماء موارد متعددة إلى الفاتورة نفسها. وتكون أسماء موارد الفواتير على النحو التالي:

customers/{customerId}/invoices/{invoice_id}
type

enum (InvoiceType)

النتائج فقط. نوع الفاتورة.
serviceDateRange

object (DateRange)

النتائج فقط. النطاق الزمني لفترة الخدمة لهذه الفاتورة. تاريخ الانتهاء شامل.
adjustmentsSubtotalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي الفرعي قبل الضريبة لتعديلات مستوى الفاتورة، بوحدات المايكرو.
adjustmentsTaxAmountMicros

string (int64 format)

النتائج فقط. مجموع الضرائب على التسويات على مستوى الفاتورة، بالمايكرو.
adjustmentsTotalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي للتعديلات على مستوى الفاتورة بوحدات المايكرو.
regulatoryCostsSubtotalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي الفرعي قبل الضريبة للتكاليف التنظيمية على مستوى الفاتورة بالمايكرو.
regulatoryCostsTaxAmountMicros

string (int64 format)

النتائج فقط. مجموع الضرائب على التكاليف التنظيمية على مستوى الفاتورة، بالمايكرو.
regulatoryCostsTotalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي للتكاليف التنظيمية على مستوى الفاتورة بالميكرو ثانية
replacedInvoices[]

string

النتائج فقط. اسم مورد الفواتير الأصلية التي تتم إعادة إرسال الفواتير إليها أو استبدالها بهذه الفاتورة، إذا كان ذلك منطبقًا قد يكون هناك عدة فواتير تم استبدالها بسبب دمج الفواتير. لا يمكن أن تنتمي الفواتير التي تم استبدالها إلى حساب الدفعات نفسه. إذا تم ضبط replacedInvoices، لن يتم ضبط correctedInvoice. وتكون أسماء موارد الفواتير على النحو التالي:

customers/{customerId}/invoices/{invoice_id}
accountBudgetSummaries[]

object (AccountBudgetSummary)

النتائج فقط. قائمة معلومات ملخّصة لميزانية الحساب المرتبطة بهذه الفاتورة.
accountSummaries[]

object (AccountSummary)

النتائج فقط. قائمة معلومات الحساب الموجزة المرتبطة بهذه الفاتورة.
id

string

النتائج فقط. رقم تعريف الفاتورة. ويظهر هذا الرقم في ملف PDF للفاتورة باسم "رقم الفاتورة".
billingSetup

string

النتائج فقط. اسم المورد لإعداد فوترة هذه الفاتورة.

customers/{customerId}/billingSetups/{billing_setup_id}
paymentsAccountId

string

النتائج فقط. معرّف مكوّن من 16 رقمًا يُستخدم لتحديد حساب الدفعات المرتبط بإعدادات الفوترة، مثلاً " 1234-5678-9012-3456". ويظهر هذا الرقم في ملف الفاتورة بتنسيق PDF باسم "رقم حساب الفوترة".
paymentsProfileId

string

النتائج فقط. معرّف مكوّن من 12 رقمًا يُستخدم لتحديد الملف الشخصي للدفع المرتبط بإعدادات الفوترة، مثلاً " 1234-5678-9012". ويظهر هذا العنوان في ملف الفاتورة بتنسيق PDF باسم "معرّف الفوترة".
issueDate

string

النتائج فقط. تمثل هذه السمة تاريخ الإصدار بالتنسيق yyyy-mm-dd. ويظهر هذا العنوان في ملف الفاتورة بتنسيق PDF على أنّه "تاريخ الإصدار" أو "تاريخ الفاتورة".
dueDate

string

النتائج فقط. تمثل هذه السمة تاريخ التسليم بالتنسيق yyyy-mm-dd.
currencyCode

string

النتائج فقط. تمثّل هذه السمة رمز العملة. يتم إرجاع جميع التكاليف بهذه العملة. تتوفّر مجموعة فرعية من رموز العملات المشتقة من معيار ISO 4217.
exportChargeSubtotalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي الفرعي قبل الضريبة لرسوم التصدير على مستوى الفاتورة بالميكرو ثانية.
exportChargeTaxAmountMicros

string (int64 format)

النتائج فقط. مجموع الضرائب على رسوم التصدير على مستوى الفاتورة بالمايكرو.
exportChargeTotalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي لرسوم التصدير على مستوى الفاتورة بوحدات المايكرو.
subtotalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي الفرعي قبل الضريبة بوحدات المايكرو. ويساوي هذا مجموع مبالغ الإجمالي الفرعي AccountBudgetSummary وInvoice.resetments_subtotal_amount_micros.
taxAmountMicros

string (int64 format)

النتائج فقط. مجموع كل الضرائب الظاهرة على الفاتورة بوحدات المايكرو. وهذا يساوي مجموع مبالغ الضريبة AccountBudgetSummary، بالإضافة إلى الضرائب غير المرتبطة بميزانية حساب محددة.
totalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي بوحدات المايكرو. ويساوي هذا مجموع Invoice.subtotal_amount_micros وInvoice.tax_amount_micros وInvoice.regulatory_costs_subtotal_amount_micros وInvoice.export_charge_subtotal_amount_micros (مفصولاً في عنصر منفصل يبدأ بـ V14.1).
correctedInvoice

string

النتائج فقط. اسم مورد الفاتورة الأصلية بعد تصحيحها أو شطبها أو إلغاؤها بموجب هذه الفاتورة، إذا كان ذلك منطبقًا. إذا تم ضبط correctedInvoice، لن يتم ضبط replacedInvoices. وتكون أسماء موارد الفواتير على النحو التالي:

customers/{customerId}/invoices/{invoice_id}
pdfUrl

string

النتائج فقط. عنوان URL لنسخة PDF من الفاتورة. على المستخدمين إدخال رمز OAuth المميز لطلب ملف PDF باستخدام عنوان URL هذا.

InvoiceType

تمثّل هذه السمة النوع المحتمل من الفواتير.

عمليات التعداد
UNSPECIFIED عدم تحديد صيغة مخاطبة
UNKNOWN تُستخدَم هذه السمة للقيمة المعروضة فقط. يعرض قيمة غير معروفة في هذا الإصدار.
CREDIT_MEMO فاتورة بقيمة سالبة. يتلقّى الحساب رصيدًا.
INVOICE فاتورة بقيمة موجبة يجب دفع رصيد في الحساب.

AccountBudgetSummary

يُمثِّل ذلك تكلفة موجزة قابلة للفوترة لميزانية الحساب.

تمثيل JSON 
{
  "billableActivityDateRange": {
    object (DateRange)
  },
  "invalidActivitySummaries": [
    {
      object (InvalidActivitySummary)
    }
  ],
  "customer": string,
  "customerDescriptiveName": string,
  "accountBudget": string,
  "accountBudgetName": string,
  "purchaseOrderNumber": string,
  "subtotalAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string,
  "servedAmountMicros": string,
  "billedAmountMicros": string,
  "overdeliveryAmountMicros": string,
  "invalidActivityAmountMicros": string
}
الحقول
billableActivityDateRange

object (DateRange)

النتائج فقط. النطاق الزمني للنشاط القابل للفوترة لميزانية الحساب، ضمن النطاق الزمني لهذه الخدمة تاريخ الانتهاء شامل. ويمكن أن يختلف هذا الوقت عن وقتَي البدء والانتهاء لميزانية الحساب.
invalidActivitySummaries[]

object (InvalidActivitySummary)

النتائج فقط. قائمة بأرصدة الأنشطة غير الصالحة الملخصة مع عمليات الربط الأصلية
customer

string

النتائج فقط. اسم المورد للعميل المرتبط بميزانية الحساب هذه. يحتوي هذا على الرقم التعريفي للعميل الذي يظهر في ملف PDF للفاتورة باسم "رقم تعريف الحساب". تكون أسماء موارد العملاء على النحو التالي:

customers/{customerId}
customerDescriptiveName

string

النتائج فقط. الاسم الوصفي لعميل ميزانية الحساب. ويظهر هذا العنوان في ملف الفاتورة بتنسيق PDF باسم "الحساب".
accountBudget

string

النتائج فقط. اسم مورد ميزانية الحساب المرتبطة بهذه التكلفة الملخصة القابلة للفوترة. تكون أسماء موارد AccountBudget على النحو التالي:

customers/{customerId}/accountBudgets/{account_budget_id}
accountBudgetName

string

النتائج فقط. اسم ميزانية الحساب. ويظهر هذا العنوان في ملف الفاتورة بتنسيق PDF باسم "ميزانية الحساب".
purchaseOrderNumber

string

النتائج فقط. رقم طلب الشراء لميزانية الحساب. ويظهر هذا الرقم في ملف الفاتورة بتنسيق PDF باسم "طلب شراء".
subtotalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي الفرعي قبل الضريبة المنسوب إلى هذه الميزانية خلال فترة الخدمة بالمايكرو.
taxAmountMicros

string (int64 format)

النتائج فقط. مبلغ الضريبة المنسوب إلى هذه الميزانية خلال فترة الخدمة بالمايكرو.
totalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي الذي يعود إلى هذه الميزانية خلال فترة الخدمة بالمايكرو. يعادل هذا المبلغ مجموع مبلغ الإجمالي الفرعي لميزانية الحساب ومبلغ ضريبة ميزانية الحساب.
servedAmountMicros

string (int64 format)

النتائج فقط. المبلغ المعروض مسبقًا الناتج عن هذه الميزانية خلال فترة الخدمة، بالميكرو ثانية. ويكون هذا مفيدًا فقط في تسوية بيانات الفاتورة والتسليم.
billedAmountMicros

string (int64 format)

النتائج فقط. المبلغ المذكور مسبقًا في الفاتورة والمنسوب إلى هذه الميزانية خلال فترة الخدمة، بالميكرو ثانية. وهذا لا يأخذ في الحسبان أي تسويات.
overdeliveryAmountMicros

string (int64 format)

النتائج فقط. مبلغ العرض الزائد قبل الضريبة المنسوب إلى هذه الميزانية أثناء فترة الخدمة، بالمايكرو (القيمة السالبة).
invalidActivityAmountMicros

string (int64 format)

النتائج فقط. مبلغ النشاط غير الصالح قبل الضريبة المنسوب إلى هذه الميزانية في الأشهر السابقة، بالميكرو (قيمة سالبة).

InvalidActivitySummary

تفاصيل عن النشاط غير الصالح للفاتورة التي تتضمّن تفاصيل إضافية عن الفاتورة التي يتم إجراء التصحيحات عليها.

تمثيل JSON 
{
  "originalMonthOfService": enum (MonthOfYear),
  "originalYearOfService": string,
  "originalInvoiceId": string,
  "originalAccountBudgetName": string,
  "originalPurchaseOrderNumber": string,
  "amountMicros": string
}
الحقول
originalMonthOfService

enum (MonthOfYear)

النتائج فقط. شهر الخدمة الأصلي المرتبط برصيد النشاط غير الصالح هذا.
originalYearOfService

string

النتائج فقط. سنة الخدمة الأصلية المرتبطة برصيد النشاط غير الصالح هذا.
originalInvoiceId

string

النتائج فقط. رقم الفاتورة الأصلي المرتبط برصيد النشاط غير الصالح هذا
originalAccountBudgetName

string

النتائج فقط. اسم ميزانية الحساب الأصلي المرتبط برصيد النشاط غير الصالح هذا.
originalPurchaseOrderNumber

string

النتائج فقط. رقم طلب الشراء الأصلي المرتبط برصيد النشاط غير الصالح هذا.
amountMicros

string (int64 format)

النتائج فقط. مقدار النشاط غير صالح بوحدات المايكرو.

AccountSummary

يمثل عرضًا موجزًا على مستوى الحساب.

تمثيل JSON 
{
  "customer": string,
  "billingCorrectionSubtotalAmountMicros": string,
  "billingCorrectionTaxAmountMicros": string,
  "billingCorrectionTotalAmountMicros": string,
  "couponAdjustmentSubtotalAmountMicros": string,
  "couponAdjustmentTaxAmountMicros": string,
  "couponAdjustmentTotalAmountMicros": string,
  "excessCreditAdjustmentSubtotalAmountMicros": string,
  "excessCreditAdjustmentTaxAmountMicros": string,
  "excessCreditAdjustmentTotalAmountMicros": string,
  "regulatoryCostsSubtotalAmountMicros": string,
  "regulatoryCostsTaxAmountMicros": string,
  "regulatoryCostsTotalAmountMicros": string,
  "exportChargeSubtotalAmountMicros": string,
  "exportChargeTaxAmountMicros": string,
  "exportChargeTotalAmountMicros": string,
  "subtotalAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string
}
الحقول
customer

string

النتائج فقط. الحساب المرتبط بملخّص الحساب.
billingCorrectionSubtotalAmountMicros

string (int64 format)

النتائج فقط. مبلغ الإجمالي الفرعي لتصحيح الفوترة قبل الضريبة بالمايكرو.
billingCorrectionTaxAmountMicros

string (int64 format)

النتائج فقط. الضريبة على تصحيح الفوترة، بالمايكرو.
billingCorrectionTotalAmountMicros

string (int64 format)

النتائج فقط. إجمالي مبلغ تصحيح الفوترة بالمايكرو
couponAdjustmentSubtotalAmountMicros

string (int64 format)

النتائج فقط. قيمة المجموع الفرعي لتسوية قيمة قسيمة الضريبة مسبقًا بالمايكرو.
couponAdjustmentTaxAmountMicros

string (int64 format)

النتائج فقط. الضريبة على تسوية القسيمة، بالمايكرو.
couponAdjustmentTotalAmountMicros

string (int64 format)

النتائج فقط. إجمالي مبلغ تعديل القسيمة بوحدات المايكرو
excessCreditAdjustmentSubtotalAmountMicros

string (int64 format)

النتائج فقط. المبلغ الإجمالي الفرعي لتسوية الرصيد الزائد قبل الضريبة، بالمايكرو.
excessCreditAdjustmentTaxAmountMicros

string (int64 format)

النتائج فقط. الضريبة على تسوية الرصيد الزائد، بالمايكرو.
excessCreditAdjustmentTotalAmountMicros

string (int64 format)

النتائج فقط. إجمالي مبلغ تسوية الرصيد الزائد بالمايكرو.
regulatoryCostsSubtotalAmountMicros

string (int64 format)

النتائج فقط. مبلغ الإجمالي الفرعي للتكاليف التنظيمية قبل احتساب الضريبة، بالمايكرو.
regulatoryCostsTaxAmountMicros

string (int64 format)

النتائج فقط. الضريبة على التكاليف التنظيمية، بالمايكرو.
regulatoryCostsTotalAmountMicros

string (int64 format)

النتائج فقط. إجمالي مبلغ التكاليف التنظيمية بالمايكرو.
exportChargeSubtotalAmountMicros

string (int64 format)

النتائج فقط. مبلغ الإجمالي الفرعي لرسوم قبل ضريبة التصدير بالمايكرو.
exportChargeTaxAmountMicros

string (int64 format)

النتائج فقط. الضريبة على رسوم التصدير، بالمايكرو.
exportChargeTotalAmountMicros

string (int64 format)

النتائج فقط. إجمالي مبلغ رسوم التصدير بالمايكرو.
subtotalAmountMicros

string (int64 format)

النتائج فقط. إجمالي المبلغ الإجمالي الفرعي قبل احتساب الضريبة المتعلّق بالحساب أثناء فترة الخدمة، بالميكرو ثانية.
taxAmountMicros

string (int64 format)

النتائج فقط. إجمالي مبلغ الضريبة المنسوب إلى الحساب أثناء فترة الخدمة بالمايكرو.
totalAmountMicros

string (int64 format)

النتائج فقط. إجمالي المبلغ المنسوب إلى الحساب أثناء فترة الخدمة بالمايكرو. ويساوي هذا مجموع subtotalAmountMicros وtaxAmountMicros.