Method: customers.invoices.list

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

قائمة الأخطاء التي تظهر: AuthenticationError AuthorizationError FieldError HeaderError InternalError InvoiceError QuotaError RequestError

طلب HTTP

GET https://googleads.googleapis.com/v14/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 رقمًا يُستخدَم لتحديد الملف الشخصي للدفع المرتبط بإعدادات الفوترة، على سبيل المثال "9012-5678-1234". ويظهر في ملف 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.adjustments_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.