برای گفتگو و ارائه بازخورد در مورد محصولات ما، به کانال رسمی Google Ads Discord در سرور انجمن تبلیغات و اندازه گیری Google بپیوندید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

صورتحساب

فاکتورهای ماهانه برای یک حساب گوگل ادز را می‌توان با استفاده از InvoiceService بازیابی کرد.

پیش‌نیازها

صدور صورتحساب ماهانه را برای حساب گوگل ادز فعال کنید. برای یادگیری نحوه مدیریت صورتحساب با استفاده از API گوگل ادز، به راهنماهای مربوط به تنظیمات صورتحساب حساب و بودجه مراجعه کنید.
در صورت تنظیم، login-customer-id باید شناسه مشتری یک حساب کاربری مدیر را مشخص کند که حساب Google Ads را که برای آن فاکتورها را بازیابی می‌کنید، مدیریت می‌کند. این به عنوان مدیر پرداخت در رابط کاربری Google Ads برچسب گذاری شده است.

فاکتورها را بازیابی کنید

برای بازیابی فاکتورها، باید متد InvoiceService.ListInvoices را درخواست کنید و تمام فیلدهای مورد نیاز در ListInvoicesRequest شامل customer_id ، billing_setup ، issue_year و issue_month را تنظیم کنید.

اگر تنظیمات صورتحساب تجمیعی دارید، API گوگل ادز فاکتورهای مربوط به همه مشتریان تحت یک تنظیمات صورتحساب یکسان را برمی‌گرداند، نه فقط فاکتور مربوط به customer_id مشخص شده در درخواست API.

customer_id باید یک حساب کاربری سرویس‌دهنده‌ی گوگل ادز باشد. برای دریافت تمام فاکتورهای یک مدیر پرداخت، برای هر حساب کاربری سرویس‌دهنده‌ی گوگل ادز یک درخواست ارسال کنید.

در اینجا یک مثال آورده شده است:

جاوا

// Issues the request.
ListInvoicesResponse response =
    invoiceServiceClient.listInvoices(
        String.valueOf(customerId),
        ResourceNames.billingSetup(customerId, billingSetupId),
        String.valueOf(oneMonthAgo.getYear()),
        MonthOfYear.valueOf(oneMonthAgo.getMonth().toString()));GetInvoices.java

سی شارپ

ListInvoicesResponse response = invoiceServiceClient.ListInvoices(customerId.ToString(),
    ResourceNames.BillingSetup(customerId, billingSetupId),
    // Year must be 2019 or later.
    lastMonthDateTime.Year.ToString("yyyy"),
    lastMonth);GetInvoices.cs

پی اچ پی

// Issues the request.
$response = $googleAdsClient->getInvoiceServiceClient()->listInvoices(
    ListInvoicesRequest::build(
        $customerId,
        ResourceNames::forBillingSetup($customerId, $billingSetupId),
        // The year needs to be 2019 or later.
        date('Y', $lastMonth),
        MonthOfYear::value(strtoupper(date('F', $lastMonth)))
    )
);GetInvoices.php

پایتون

# Issues a request to list invoices.
response = client.get_service("InvoiceService").list_invoices(
    customer_id=customer_id,
    billing_setup=client.get_service("GoogleAdsService").billing_setup_path(
        customer_id, billing_setup_id
    ),
    # The year needs to be 2019 or later, per the docs:
    # https://developers.google.com/google-ads/api/docs/billing/invoice?hl=en#retrieving_invoices
    issue_year=str(last_month.year),
    issue_month=last_month.strftime("%B").upper(),
)get_invoices.py

روبی

# Issues a request to list invoices.
response = client.service.invoice.list_invoices(
  customer_id: customer_id,
  billing_setup: client.path.billing_setup(customer_id, billing_setup_id),
  # The year needs to be 2019 or later.
  issue_year: last_month.year.to_s,
  # '%^B' option returns the uppercased full month name (e.g. 'JANUARY').
  issue_month: last_month.strftime("%^B").to_sym,
)get_invoices.rb

پرل

# Issue the request.
my $response = $api_client->InvoiceService()->list({
    customerId   => $customer_id,
    billingSetup =>
      Google::Ads::GoogleAds::V22::Utils::ResourceNames::billing_setup(
      ($customer_id, $billing_setup_id)
      ),
    # The year needs to be 2019 or later.
    issueYear  => strftime("%Y", @last_month),
    issueMonth => uc(strftime("%B", @last_month))});get_invoices.pl

حلقه زدن

# This code example gets invoices for a given billing setup.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   DEVELOPER_TOKEN,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
#   BILLING_SETUP_ID: The billing setup resource name of the requested invoices.
#   ISSUE_MONTH: The issue month of the invoice, for example, JANUARY.
#   ISSUE_YEAR: The issue year to retrieve invoices, in yyyy format.
curl -f "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/invoices?billingSetup=${BILLING_SETUP_ID}&issueMonth=${ISSUE_MONTH}&issueYear=${ISSUE_YEAR}" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}"get_invoices.sh

پاسخ یک شیء ListInvoicesResponse است که شامل فهرستی از Invoices منطبق است که هر کدام شامل مجموعه بزرگی از فیلدها مانند موارد زیر هستند:

شناسه‌ها: payments_account_id ، payments_profile_id .
زمان: issue_date ، due_date ، service_date_range .
مبالغ: subtotal_amount_micros ، tax_amount_micros ، total_amount_micros .
پی‌دی‌اف: pdf_url . برای دستورالعمل دانلود فایل پی‌دی‌اف فاکتور به اینجا مراجعه کنید.
تاریخچه: corrected_invoice ، replaced_invoices .

همچنین در صورت لزوم شامل فیلدهای خاص دیگری نیز می‌شود:

تعدیلات : adjustments_subtotal_amount_micros ، adjustments_tax_amount_micros ، adjustments_total_amount_micros .
هزینه‌های نظارتی : regulatory_costs_subtotal_amount_micros ، regulatory_costs_tax_amount_micros ، regulatory_costs_total_amount_micros .
صدور هزینه‌ها : export_charge_subtotal_amount_micros ، export_charge_tax_amount_micros ، export_charge_total_amount_micros .

جزئیات بودجه را دریافت کنید

یک Invoice اطلاعات دقیقی در مورد بودجه‌های حساب‌های مرتبط را به صورت فهرستی از اشیاء AccountBudgetSummary در فیلد account_budget_summaries ارائه می‌دهد:

شناسه‌ها: customer ، account_budget ، purchase_order_number .
زمان: billable_activity_date_range .
مبالغ: subtotal_amount_micros ، tax_amount_micros ، total_amount_micros ، ریز مبلغ invalid_activity_amount_micros ، billed_amount_micros ، served_amount_micros ، overdelivery_amount_micros .

دریافت جزئیات حساب

یک Invoice اطلاعاتی در مورد حساب‌های مرتبط را به صورت فهرستی از اشیاء AccountSummary در فیلد account_summaries ارائه می‌دهد. این شامل جزئیاتی در مورد اصلاحات صورتحساب، تعدیلات، هزینه‌های صادرات و هزینه‌های نظارتی است.

درک مقادیر

تمام مبالغ ارائه شده در اشیاء AccountBudgetSummary ، AccountSummary و Invoice در طول دوره‌های سرویس‌دهی‌شان قابل انتساب هستند و طبق این قوانین ارزیابی می‌شوند:

`AccountBudgetSummary`	قانون ارزیابی
`served_amount_micros`	حساب کاربری \ بودجه \ هزینه شده $
`billed_amount_micros`	حساب \ بودجه \ صورتحساب $
`overdelivery_amount_micros`	$account\_budget\_overdelivery$
`invalid_activity_amount_micros`	حساب کاربری \ بودجه \ فعالیت \ نامعتبر \ فعالیت $
`subtotal_amount_micros`	حساب \ بودجه \ پیش از کسر مالیات $
`tax_amount_micros`	حساب \ بودجه \ مالیات $
`total_amount_micros`	حساب \ بودجه \ پیش از کسر مالیات + $ حساب \ بودجه \ مالیات $

`AccountSummary`	قانون ارزیابی
`billing_correction_subtotal_amount_micros`	حساب \ صورتحساب \ اصلاح \ پیش از کسر مالیات $
`coupon_adjustment_subtotal_amount_micros`	حساب \ کوپن \ تعدیل \ پیش پرداخت $
`excess_credit_adjustment_subtotal_amount_micros`	حساب \ مازاد \ اعتبار \ تعدیل \ پیش پرداخت \ مالیات $
`regulatory_costs_subtotal_amount_micros`	حساب \\هزینه‌های نظارتی \\قبل از مالیات $
`export_charge_subtotal_amount_micros`	حساب \\صادرات \\شارژ \\پیش پرداخت $
`billing_correction_tax_amount_micros`	حساب \ صورتحساب \ اصلاح \ مالیات $
`coupon_adjustment_tax_amount_micros`	حساب \ کوپن \ تعدیل \ مالیات $
`excess_credit_adjustment_tax_amount_micros`	حساب \ مازاد \ اعتبار \ تعدیل \ مالیات $
`regulatory_costs_tax_amount_micros`	حساب \\هزینه‌های نظارتی \\مالیات $
`export_charge_tax_amount_micros`	حساب \\صادرات \\هزینه \\مالیات $
`billing_correction_total_amount_micros`	حساب \_صورتحساب \_اصلاح \_پیش_مالیات + $ حساب \ صورتحساب \ اصلاح \ مالیات $
`coupon_adjustment_total_amount_micros`	حساب \_کوپن \_تعدیل \_پیش_مالیات + $ حساب \ کوپن \ تعدیل \ مالیات $
`excess_credit_adjustment_total_amount_micros`	حساب \ مازاد \ اعتبار \ تعدیل \ پیش پرداخت مالیات + $ حساب \ مازاد \ اعتبار \ تعدیل \ مالیات $
`regulatory_costs_total_amount_micros`	حساب \\هزینه‌های نظارتی \\پیش از کسر مالیات + $ حساب \\هزینه‌های نظارتی \\مالیات $
`export_charge_total_amount_micros`	حساب \\صادرات \\شارژ \\پیش پرداخت + $ حساب \\صادرات \\هزینه \\مالیات $
`subtotal_amount_micros`	حساب کاربری \ پیش از کسر مالیات $
`tax_amount_micros`	حساب کاربری
`total_amount_micros`	حساب کاربری \_پیش_مالیات + $ حساب کاربری

`Invoice`	قانون ارزیابی
`adjustments_subtotal_amount_micros`	$\sum_{i=1}^n حساب\_صورتحساب\_تصحیح\_پیش_مالیات_i + $ $\sum_{i=1}^n حساب\_کوپن\_تعدیل\_پیش_مالیات_i + $ حساب \مازاد \اعتبار \تعدیل \پیش مالیات \i$
`regulatory_costs_subtotal_amount_micros`	حساب \\sum_{i=1}^n \\هزینه‌های نظارتی \\پیش مالیات \\i $
`export_charge_subtotal_amount_micros`	حساب \\sum_{i=1}^n $\\export\\charge\\pretax_i$
`adjustments_tax_amount_micros`	$\sum_{i=1}^n حساب\_صورتحساب\_اصلاح\_مالیات_i + $ $\sum_{i=1}^n حساب\کوپن\تعدیل\مالیات_i + $ $\sum_{i=1}^n حساب\_مازاد\_اعتبار\_تعدیل\_مالیات_i$
`regulatory_costs_tax_amount_micros`	حساب \\sum_{i=1}^n $\\هزینه‌های نظارتی \\مالیات_i$
`export_charge_tax_amount_micros`	$\sum_{i=1}^n حساب\_export\_charge\_tax_i$
`adjustments_total_amount_micros`	تعدیلات پیش از کسر مالیات + $ تعدیلات_مالیات$
`regulatory_costs_total_amount_micros`	هزینه‌های نظارتی قبل از کسر مالیات + $ هزینه‌های نظارتی، مالیات
`export_charge_total_amount_micros`	هزینه صادرات\پیش پرداخت\صادرات + $ هزینه صادرات\مالیات$
`subtotal_amount_micros`	تعدیلات پیش از کسر مالیات + $ حساب \بودجه \پیش_مالیات \sum_{i=1}^n $
`tax_amount_micros`	تعدیلات_مالیات + $ هزینه‌های نظارتی و مالیاتی + $ هزینه صادرات\مالیات\مالیات + $ حساب \بودجه \مالیات \i$
`total_amount_micros`	$قبل از مالیات + $ هزینه‌های نظارتی قبل از کسر مالیات + $ هزینه صادرات\پیش پرداخت\صادرات + $ مالیات

در اینجا مثالی از نحوه تکرار فاکتورهای بازیابی شده آورده شده است:

}

{ }

foreach }

- end

}

irection:rtl">

جاوا

// Iterates over all invoices retrieved and prints their information. for (Invoice invoice : response.getInvoicesList()) { System.out.printf( "- Found the invoice '%s':\n" + "  ID (also known as Invoice Number): '%s'\n" + "  Type: %s\n" + "  Billing setup ID: '%s'\n" + "  Payments account ID (also known as Billing Account Number): '%s'\n" + "  Payments profile ID (also known as Billing ID): '%s'\n" + "  Issue date (also known as Invoice Date): %s\n" + "  Due date: %s\n" + "  Currency code: %s\n" + "  Service date range (inclusive): from %s to %s\n" + "  Adjustments: subtotal '%.2f', tax '%.2f', total '%.2f'\n" + "  Regulatory costs: subtotal '%.2f', tax '%.2f', total '%.2f'\n" + "  Replaced invoices: '%s'\n" + "  Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'\n" + "  Corrected invoice: '%s'\n" + "  PDF URL: '%s'\n" + "  Account budgets: ", invoice.getResourceName(), invoice.getId(), invoice.getType(), invoice.getBillingSetup(), invoice.getPaymentsAccountId(), invoice.getPaymentsProfileId(), invoice.getIssueDate(), invoice.getDueDate(), invoice.getCurrencyCode(), invoice.getServiceDateRange().getStartDate(), invoice.getServiceDateRange().getEndDate(), convertMicrosToCurrency(invoice.getAdjustmentsSubtotalAmountMicros()), convertMicrosToCurrency(invoice.getAdjustmentsTaxAmountMicros()), convertMicrosToCurrency(invoice.getAdjustmentsTotalAmountMicros()), convertMicrosToCurrency(invoice.getRegulatoryCostsSubtotalAmountMicros()), convertMicrosToCurrency(invoice.getRegulatoryCostsTaxAmountMicros()), convertMicrosToCurrency(invoice.getRegulatoryCostsTotalAmountMicros()), invoice.getReplacedInvoicesList(), convertMicrosToCurrency(invoice.getSubtotalAmountMicros()), convertMicrosToCurrency(invoice.getTaxAmountMicros()), convertMicrosToCurrency(invoice.getTotalAmountMicros()), invoice.getCorrectedInvoice(), invoice.getPdfUrl()); for (AccountBudgetSummary accountBudgetSummary : invoice.getAccountBudgetSummariesList()) { System.out.printf( "  - Account budget '%s':\n" + "      Name (also known as Account Budget): '%s'\n" + "      Customer (also known as Account ID): '%s'\n" + "      Customer descriptive name (also known as Account): '%s'\n" + "      Purchase order number (also known as Purchase Order): '%s'\n" + "      Billing activity date range (inclusive): from %s to %s\n" + "      Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'\n", accountBudgetSummary.getAccountBudget(), accountBudgetSummary.getAccountBudgetName(), accountBudgetSummary.getCustomer(), accountBudgetSummary.getCustomerDescriptiveName(), accountBudgetSummary.getPurchaseOrderNumber(), accountBudgetSummary.getBillableActivityDateRange().getStartDate(), accountBudgetSummary.getBillableActivityDateRange().getEndDate(), convertMicrosToCurrency(accountBudgetSummary.getSubtotalAmountMicros()), convertMicrosToCurrency(accountBudgetSummary.getTaxAmountMicros()), convertMicrosToCurrency(accountBudgetSummary.getTotalAmountMicros())); } class="devsite-github-link nocode no-select">GetInvoices.java

سناریو	کد خطا
تنظیمات صورتحساب، سال صدور یا ماه صدور وجود ندارد یا خالی است.	`RequestError.REQUIRED_FIELD_MISSING`
نمی‌توان تنظیمات صورتحساب، سال صدور یا ماه صدور را تجزیه و تحلیل کرد.	`FieldError.INVALID_VALUE`
این درخواست برای فاکتورهایی است که قبل از ۱ ژانویه ۲۰۱۹ صادر شده‌اند.	`InvoiceError.YEAR_MONTH_TOO_OLD`
درخواست برای مشتری‌ای است که فاکتور دریافت نمی‌کند.	`InvoiceError.NOT_INVOICED_CUSTOMER`
کاربر اجازه مشاهده فاکتورهای تنظیمات صورتحساب را ندارد.	`AuthorizationError.ACTION_NOT_PERMITTED`

صورتحساب

پیش‌نیازها

فاکتورها را بازیابی کنید

جاوا

سی شارپ

پی اچ پی

پایتون

روبی

پرل

حلقه زدن

جزئیات بودجه را دریافت کنید

دریافت جزئیات حساب

درک مقادیر

جاوا

سی شارپ

پی اچ پی

پایتون

روبی

پرل

دانلود فاکتور به صورت PDF

کدهای خطای رایج

صورتحساب با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

پیش‌نیازها

فاکتورها را بازیابی کنید

جاوا

سی شارپ

پی اچ پی

پایتون

روبی

پرل

حلقه زدن

جزئیات بودجه را دریافت کنید

دریافت جزئیات حساب

درک مقادیر

جاوا

سی شارپ

پی اچ پی

پایتون

روبی

پرل

دانلود فاکتور به صورت PDF

کدهای خطای رایج

صورتحساب