‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

صورت حساب‌ها

صورت‌حساب‌های ماهانه برای حساب Google Ads را می‌توان بااستفاده از InvoiceService بازیابی کرد.

پیش‌نیازها

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

بازیابی صورت‌حساب‌ها

برای بازیابی صورت‌حساب‌ها، باید روش InvoiceService.ListInvoices را درخواست کنید و همه فیلدهای الزامی را در ListInvoicesRequest تنظیم کنید:

customer_id: شناسه مشتری حساب ارائه‌دهنده Google Ads.
‫billing_setup: نام منبع راه‌اندازی صورت‌حساب در قالب customers/{customer_id}/billingSetups/{billing_setup_id}.
issue_year: سال صدور به‌صورت رشته‌ای چهاررقمی (برای مثال، "2025").
issue_month: مقدار شمارشی MonthOfYear برای ماه صدور.

همچنین می‌توانید فیلد اختیاری زیر را تنظیم کنید:

include_granular_level_invoice_details: بولی اختیاری (به‌طور پیش‌فرض false). وقتی روی true تنظیم شود، اشیای Invoice برگردانده‌شده شامل تفکیک هزینه در سطح پویش (AccountBudgetSummary.campaign_summaries)، هزینه‌های نظارتی تفکیک‌شده (AccountSummary.regulatory_cost_summaries)، و تعدیل‌های تفکیک‌شده (AccountSummary.adjustment_summaries) است.

اگر تنظیم صورت‌حساب یکپارچه دارید، Google Ads API صورت‌حساب‌های همه مشتریان تحت همان تنظیم صورت‌حساب را برمی‌گرداند، نه فقط صورت‌حساب customer_id مشخص‌شده در درخواست API.

‫customer_id باید حساب ارائه‌دهنده Google Ads باشد. برای دریافت همه صورت‌حساب‌های مدیر پرداخت‌کننده، برای هر حساب ارائه‌دهنده Google Ads یک درخواست ارسال کنید.

به‌عنوان مثال:

جاوا

// 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

C#‎

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

PHP

// 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

Python

# 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

Ruby

# 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::V26::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

curl

# This code example gets invoices for a given billing setup.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   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 "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}"get_invoices.sh

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

شناسه‌ها: payments_account_id، payments_profile_id.
زمان: issue_date، due_date، service_date_range.
مبالغ: subtotal_amount_micros، tax_amount_micros، total_amount_micros.
پی‌دی‌اف: pdf_url. برای دستورالعمل‌ها، بارگیری PDF صورت‌حساب را ببینید.
سابقه: 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،‏ customer_descriptive_name،‏ account_budget،‏ account_budget_name،‏ 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.
تفکیک فعالیت نامعتبر: invalid_activity_summaries، فهرستی از InvalidActivitySummary شیء حاوی original_month_of_service، original_year_of_service، original_invoice_id، original_account_budget_name، original_purchase_order_number، و amount_micros.
تفکیک‌های سطح پویش (زمانی پر می‌شود که include_granular_level_invoice_details true باشد): campaign_summaries، فهرستی از اشیاء CampaignSummary حاوی campaign_description،‏ quantity،‏ unit_of_measure (UnitOfMeasure)، و amount_micros.

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

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

تنظیم include_granular_level_invoice_details روی true در ListInvoicesRequest همچنین فهرست‌های تفکیک‌شده زیر را در هر AccountSummary پر می‌کند:

regulatory_cost_summaries: فهرستی از RegulatoryCostSummary شیء با regulatory_fee_type (RegulatoryFeeType) و amount_micros.
adjustment_summaries: فهرستی از اشیاء AdjustmentSummary با adjustment_description و amount_micros.

مبالغ را درک کنید

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

`AccountBudgetSummary`	قانون ارزیابی
`served_amount_micros`	$account\_budget\_served$
`billed_amount_micros`	$account\_budget\_billed$
`overdelivery_amount_micros`	$account\_budget\_overdelivery$
`invalid_activity_amount_micros`	$account\_budget\_invalid\_activity$
`subtotal_amount_micros`	$account\_budget\_pretax$
`tax_amount_micros`	$account\_budget\_tax$
`total_amount_micros`	$account\_budget\_pretax + $ $account\_budget\_tax$

`AccountSummary`	قانون ارزیابی
`billing_correction_subtotal_amount_micros`	$account\_billing\_correction\_pretax$
`coupon_adjustment_subtotal_amount_micros`	$account\_coupon\_adjustment\_pretax$
`excess_credit_adjustment_subtotal_amount_micros`	$account\_excess\_credit\_adjustment\_pretax$
`regulatory_costs_subtotal_amount_micros`	$account\_regulatory\_costs\_pretax$
`export_charge_subtotal_amount_micros`	$account\_export\_charge\_pretax$
`billing_correction_tax_amount_micros`	$account\_billing\_correction\_tax$
`coupon_adjustment_tax_amount_micros`	$account\_coupon\_adjustment\_tax$
`excess_credit_adjustment_tax_amount_micros`	$account\_excess\_credit\_adjustment\_tax$
`regulatory_costs_tax_amount_micros`	$account\_regulatory\_costs\_tax$
`export_charge_tax_amount_micros`	$account\_export\_charge\_tax$
`billing_correction_total_amount_micros`	$account\_billing\_correction\_pretax + $ $account\_billing\_correction\_tax$
`coupon_adjustment_total_amount_micros`	$account\_coupon\_adjustment\_pretax + $ $account\_coupon\_adjustment\_tax$
`excess_credit_adjustment_total_amount_micros`	$account\_excess\_credit\_adjustment\_pretax + $ $account\_excess\_credit\_adjustment\_tax$
`regulatory_costs_total_amount_micros`	$account\_regulatory\_costs\_pretax + $ $account\_regulatory\_costs\_tax$
`export_charge_total_amount_micros`	$account\_export\_charge\_pretax + $ $account\_export\_charge\_tax$
`subtotal_amount_micros`	$account\_pretax$
`tax_amount_micros`	$account\_tax$
`total_amount_micros`	$account\_pretax + $ $account\_tax$

`Invoice`	قانون ارزیابی
`adjustments_subtotal_amount_micros`	$\sum_{i=1}^n account\_billing\_correction\_pretax_i + $ $\sum_{i=1}^n account\_coupon\_adjustment\_pretax_i + $ $\sum_{i=1}^n account\_excess\_credit\_adjustment\_pretax_i$
`regulatory_costs_subtotal_amount_micros`	$\sum_{i=1}^n account\_regulatory\_costs\_pretax_i$
`export_charge_subtotal_amount_micros`	$\sum_{i=1}^n account\_export\_charge\_pretax_i$
`adjustments_tax_amount_micros`	$\sum_{i=1}^n account\_billing\_correction\_tax_i + $ $\sum_{i=1}^n account\_coupon\_adjustment\_tax_i + $ $\sum_{i=1}^n account\_excess\_credit\_adjustment\_tax_i$
`regulatory_costs_tax_amount_micros`	$\sum_{i=1}^n account\_regulatory\_costs\_tax_i$
`export_charge_tax_amount_micros`	$\sum_{i=1}^n account\_export\_charge\_tax_i$
`adjustments_total_amount_micros`	$adjustments\_pretax + $ $adjustments\_tax$
`regulatory_costs_total_amount_micros`	$regulatory\_costs\_pretax + $ $regulatory\_costs\_tax$
`export_charge_total_amount_micros`	$export\_charge\_pretax + $ $export\_charge\_tax$
`subtotal_amount_micros`	$adjustments\_pretax + $ $\sum_{i=1}^n account\_budget\_pretax_i$
`tax_amount_micros`	$adjustments\_tax + $ $regulatory\_costs\_tax + $ $export\_charge\_tax + $ $\sum_{i=1}^n account\_budget\_tax_i$
`total_amount_micros`	$subtotal\_amount\_micros + $ $regulatory\_costs\_pretax + $ $export\_charge\_pretax + $ $tax\_amount\_micros$

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

جاوا

// 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()));
  }
}GetInvoices.java

C#‎

// information.
foreach (Invoice invoice in response.Invoices)
{
    Console.WriteLine(
        "- Found the invoice '{0}':\n" +
        "  ID (also known as Invoice Number): '{1}'\n" +
        "  Type: {2}\n" +
        "  Billing setup ID: '{3}'\n" +
        "  Payments account ID (also known as Billing Account Number): '{4}'\n" +
        "  Payments profile ID (also known as Billing ID): '{5}'\n" +
        "  Issue date (also known as Invoice Date): {6}\n" +
        "  Due date: {7}\n" +
        "  Currency code: {8}\n" +
        "  Service date range (inclusive): from {9} to {10}\n" +
        "  Adjustments: subtotal '{11}', tax '{12}', total '{13}'\n" +
        "  Regulatory costs: subtotal '{14}', tax '{15}', total '{16}'\n" +
        "  Replaced invoices: '{17}'\n" +
        "  Amounts: subtotal '{18}', tax '{19}', total '{20}'\n" +
        "  Corrected invoice: '{21}'\n" +
        "  PDF URL: '{22}'\n" +
        "  Account budgets:\n",
        invoice.ResourceName,
        invoice.Id,
        invoice.Type.ToString(),
        invoice.BillingSetup,
        invoice.PaymentsAccountId,
        invoice.PaymentsProfileId,
        invoice.IssueDate,
        invoice.DueDate,
        invoice.CurrencyCode,
        invoice.ServiceDateRange.StartDate,
        invoice.ServiceDateRange.EndDate,
        FormatMicros(invoice.AdjustmentsSubtotalAmountMicros),
        FormatMicros(invoice.AdjustmentsTaxAmountMicros),
        FormatMicros(invoice.AdjustmentsTotalAmountMicros),
        FormatMicros(invoice.RegulatoryCostsSubtotalAmountMicros),
        FormatMicros(invoice.RegulatoryCostsTaxAmountMicros),
        FormatMicros(invoice.RegulatoryCostsTotalAmountMicros),
        invoice.ReplacedInvoices.Count > 0
            ? string.Join("', '", invoice.ReplacedInvoices)
            : "none",
        FormatMicros(invoice.SubtotalAmountMicros),
        FormatMicros(invoice.TaxAmountMicros),
        FormatMicros(invoice.TotalAmountMicros),
        string.IsNullOrEmpty(invoice.CorrectedInvoice)
            ? invoice.CorrectedInvoice
            : "none",
        invoice.PdfUrl);
    foreach (AccountBudgetSummary accountBudgetSummary in
        invoice.AccountBudgetSummaries)
    {
        Console.WriteLine(
            "\t- Account budget '{0}':\n" +
            "\t  Name (also known as Account Budget): '{1}'\n" +
            "\t  Customer (also known as Account ID): '{2}'\n" +
            "\t  Customer descriptive name (also known as Account): '{3}'\n" +
            "\t  Purchase order number (also known as Purchase Order): '{4}'\n" +
            "\t  Billing activity date range (inclusive): from {5} to {6}\n" +
            "\t  Amounts: subtotal '{7}', tax '{8}', total '{9}'\n",
            accountBudgetSummary.AccountBudget,
            accountBudgetSummary.AccountBudgetName ?? "none",
            accountBudgetSummary.Customer,
            accountBudgetSummary.CustomerDescriptiveName ?? "none",
            accountBudgetSummary.PurchaseOrderNumber ?? "none",
            accountBudgetSummary.BillableActivityDateRange.StartDate,
            accountBudgetSummary.BillableActivityDateRange.EndDate,
            FormatMicros(accountBudgetSummary.SubtotalAmountMicros),
            FormatMicros(accountBudgetSummary.TaxAmountMicros),
            FormatMicros(accountBudgetSummary.TotalAmountMicros));
    }
}GetInvoices.cs

PHP

// Iterates over all invoices retrieved and prints their information.
foreach ($response->getInvoices() as $invoice) {
    /** @var Invoice $invoice */
    printf(
        "- Found the invoice '%s':" . PHP_EOL .
        "  ID (also known as Invoice Number): '%s'" . PHP_EOL .
        "  Type: %s" . PHP_EOL .
        "  Billing setup ID: '%s'" . PHP_EOL .
        "  Payments account ID (also known as Billing Account Number): '%s'" . PHP_EOL .
        "  Payments profile ID (also known as Billing ID): '%s'" . PHP_EOL .
        "  Issue date (also known as Invoice Date): %s" . PHP_EOL .
        "  Due date: %s" . PHP_EOL .
        "  Currency code: %s" . PHP_EOL .
        "  Service date range (inclusive): from %s to %s" . PHP_EOL .
        "  Adjustments: subtotal '%.2f', tax '%.2f', total '%.2f'" . PHP_EOL .
        "  Regulatory costs: subtotal '%.2f', tax '%.2f', total '%.2f'" . PHP_EOL .
        "  Replaced invoices: '%s'" . PHP_EOL .
        "  Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'" . PHP_EOL .
        "  Corrected invoice: '%s'" . PHP_EOL .
        "  PDF URL: '%s'" . PHP_EOL .
        "  Account budgets:" . PHP_EOL,
        $invoice->getResourceName(),
        $invoice->getId(),
        InvoiceType::name($invoice->getType()),
        $invoice->getBillingSetup(),
        $invoice->getPaymentsAccountId(),
        $invoice->getPaymentsProfileId(),
        $invoice->getIssueDate(),
        $invoice->getDueDate(),
        $invoice->getCurrencyCode(),
        $invoice->getServiceDateRange()->getStartDate(),
        $invoice->getServiceDateRange()->getEndDate(),
        Helper::microToBase($invoice->getAdjustmentsSubtotalAmountMicros()),
        Helper::microToBase($invoice->getAdjustmentsTaxAmountMicros()),
        Helper::microToBase($invoice->getAdjustmentsTotalAmountMicros()),
        Helper::microToBase($invoice->getRegulatoryCostsSubtotalAmountMicros()),
        Helper::microToBase($invoice->getRegulatoryCostsTaxAmountMicros()),
        Helper::microToBase($invoice->getRegulatoryCostsTotalAmountMicros()),
        $invoice->getReplacedInvoices()
            ? implode(
                "', '",
                iterator_to_array($invoice->getReplacedInvoices()->getIterator())
            ) : 'none',
        Helper::microToBase($invoice->getSubtotalAmountMicros()),
        Helper::microToBase($invoice->getTaxAmountMicros()),
        Helper::microToBase($invoice->getTotalAmountMicros()),
        $invoice->getCorrectedInvoice() ?: 'none',
        $invoice->getPdfUrl()
    );
    foreach ($invoice->getAccountBudgetSummaries() as $accountBudgetSummary) {
        /** @var AccountBudgetSummary $accountBudgetSummary */
        printf(
            "  - Account budget '%s':" . PHP_EOL .
            "      Name (also known as Account Budget): '%s'" . PHP_EOL .
            "      Customer (also known as Account ID): '%s'" . PHP_EOL .
            "      Customer descriptive name (also known as Account): '%s'" . PHP_EOL .
            "      Purchase order number (also known as Purchase Order): '%s'" . PHP_EOL .
            "      Billing activity date range (inclusive): from %s to %s" . PHP_EOL .
            "      Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'" . PHP_EOL,
            $accountBudgetSummary->getAccountBudget(),
            $accountBudgetSummary->getAccountBudgetName() ?: 'none',
            $accountBudgetSummary->getCustomer(),
            $accountBudgetSummary->getCustomerDescriptiveName() ?: 'none',
            $accountBudgetSummary->getPurchaseOrderNumber() ?: 'none',
            $accountBudgetSummary->getBillableActivityDateRange()->getStartDate(),
            $accountBudgetSummary->getBillableActivityDateRange()->getEndDate(),
            Helper::microToBase($accountBudgetSummary->getSubtotalAmountMicros()),
            Helper::microToBase($accountBudgetSummary->getTaxAmountMicros()),
            Helper::microToBase($accountBudgetSummary->getTotalAmountMicros())
        );
    }
}GetInvoices.php

Python

    for invoice in response.invoices:
        print(f"""
- Found the invoice {invoice.resource_name}
    ID (also known as Invoice Number): '{invoice.id}'
    Type: {invoice.type_}
    Billing setup ID: '{invoice.billing_setup}'
    Payments account ID (also known as Billing Account Number): '{invoice.payments_account_id}'
    Payments profile ID (also known as Billing ID): '{invoice.payments_profile_id}'
    Issue date (also known as Invoice Date): {invoice.issue_date}
    Due date: {invoice.due_date}
    Currency code: {invoice.currency_code}
    Service date range (inclusive): from {invoice.service_date_range.start_date} to {invoice.service_date_range.end_date}
    Adjustments:
        subtotal {_micros_to_currency(invoice.adjustments_subtotal_amount_micros)}
        tax {_micros_to_currency(invoice.adjustments_tax_amount_micros)}
        total {_micros_to_currency(invoice.adjustments_total_amount_micros)}
    Regulatory costs:
        subtotal {_micros_to_currency(invoice.regulatory_costs_subtotal_amount_micros)}
        tax {_micros_to_currency(invoice.regulatory_costs_tax_amount_micros)}
        total {_micros_to_currency(invoice.regulatory_costs_total_amount_micros)}
    Replaced invoices: {invoice.replaced_invoices.join(", ") if invoice.replaced_invoices else "none"}
    Amounts:
        subtotal {_micros_to_currency(invoice.subtotal_amount_micros)}
        tax {_micros_to_currency(invoice.tax_amount_micros)}
        total {_micros_to_currency(invoice.total_amount_micros)}
    Corrected invoice: {invoice.corrected_invoice or "none"}
    PDF URL: {invoice.pdf_url}
    Account budgets:
    """)
        for account_budget_summary in invoice.account_budget_summaries:
            print(f"""
                  - Account budget '{account_budget_summary.account_budget}':
                      Name (also known as Account Budget): '{account_budget_summary.account_budget_name}'
                      Customer (also known as Account ID): '{account_budget_summary.customer}'
                      Customer descriptive name (also known as Account): '{account_budget_summary.customer_descriptive_name}'
                      Purchase order number (also known as Purchase Order): '{account_budget_summary.purchase_order_number}'
                      Billing activity date range (inclusive):
                        from #{account_budget_summary.billable_activity_date_range.start_date}
                        to #{account_budget_summary.billable_activity_date_range.end_date}
                      Amounts:
                        subtotal '{_micros_to_currency(account_budget_summary.subtotal_amount_micros)}'
                        tax '{_micros_to_currency(account_budget_summary.tax_amount_micros)}'
                        total '{_micros_to_currency(account_budget_summary.total_amount_micros)}'
                """)get_invoices.py

Ruby

# Iterates over all invoices retrieved and prints their information.
response.invoices.each do |invoice|
  puts <<~OUTPUT
  - Found the invoice '#{invoice.resource_name}'
    ID (also known as Invoice Number): '#{invoice.id}'
    Type: #{invoice.type}
    Billing Setup ID: '#{invoice.billing_setup}'
    Payments account ID (also known as Billing Account Number): '#{invoice.payments_account_id}'
    Payments profile ID (also known as Billing ID): '#{invoice.payments_profile_id}'
    Issue date (also known as Invoice Date): #{invoice.issue_date}
    Due date: #{invoice.due_date}
    Currency code: #{invoice.currency_code}
    Service date range (inclusive):
      from #{invoice.service_date_range.start_date}
      to #{invoice.service_date_range.end_date}
    Adjustments:
      subtotal '#{micro_to_base(invoice.adjustments_subtotal_amount_micros)}'
      tax '#{micro_to_base(invoice.adjustments_tax_amount_micros)}'
      total '#{micro_to_base(invoice.adjustments_total_amount_micros)}'
    Regulatory costs:
      subtotal '#{micro_to_base(invoice.regulatory_costs_subtotal_amount_micros)}'
      tax '#{micro_to_base(invoice.regulatory_costs_tax_amount_micros)}'
      total '#{micro_to_base(invoice.regulatory_costs_total_amount_micros)}'
    Replaced invoices: '#{invoice.replaced_invoices ? invoice.replaced_invoices.join(", ") : 'none'}'
    Amounts:
      subtotal '#{micro_to_base(invoice.subtotal_amount_micros)}'
      tax '#{micro_to_base(invoice.tax_amount_micros)}'
      total '#{micro_to_base(invoice.total_amount_micros)}'
    Corrected invoice: '#{invoice.corrected_invoices ? invoice.corrected_invoices : 'none'}'
    PDF URL: '#{invoice.pdf_url}'
    Account budgets:
  OUTPUT
  invoice.account_budget_summaries.each do |account_budget_summary|
    puts <<~OUTPUT
    \tAccount budget '#{account_budget_summary.account_budget}':
    \t  Name (also known as Account Budget): '#{account_budget_summary.account_budget_name}'
    \t  Customer (also known as Account ID): '#{account_budget_summary.customer}'
    \t  Customer descriptive name (also known as Account): '#{account_budget_summary.customer_descriptive_name}'
    \t  Purchase order number (also known as Purchase Order): '#{account_budget_summary.purchase_order_number}'
    \t  Billing activity date range (inclusive):
    \t    from #{account_budget_summary.billable_activity_date_range.start_date}
    \t    to #{account_budget_summary.billable_activity_date_range.end_date}
    \t  Amounts:
    \t    subtotal '#{micro_to_base(account_budget_summary.subtotal_amount_micros)}'
    \t    tax '#{micro_to_base(account_budget_summary.tax_amount_micros)}'
    \t    total '#{micro_to_base(account_budget_summary.total_amount_micros)}'
    OUTPUT
  end
endget_invoices.rb

پرل

# Iterate over all invoices retrieved and print their information.
foreach my $invoice (@$response) {
  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:\n",
    $invoice->{resourceName},
    $invoice->{id},
    $invoice->{type},
    $invoice->{billingSetup},
    $invoice->{paymentsAccountId},
    $invoice->{paymentsProfileId},
    $invoice->{issueDate},
    $invoice->{dueDate},
    $invoice->{currencyCode},
    $invoice->{serviceDateRange}{startDate},
    $invoice->{serviceDateRange}{endDate},
    micro_to_base($invoice->{adjustmentsSubtotalAmountMicros}),
    micro_to_base($invoice->{adjustmentsTaxAmountMicros}),
    micro_to_base($invoice->{adjustmentsTotalAmountMicros}),
    micro_to_base($invoice->{regulatoryCostsSubtotalAmountMicros}),
    micro_to_base($invoice->{regulatoryCostsTaxAmountMicros}),
    micro_to_base($invoice->{regulatoryCostsTotalAmountMicros}),
    $invoice->{replacedInvoices}
    ? join(',', @{$invoice->{replacedInvoices}})
    : "none",
    micro_to_base($invoice->{subtotalAmountMicros}),
    micro_to_base($invoice->{taxAmountMicros}),
    micro_to_base($invoice->{totalAmountMicros}),
    $invoice->{correctedInvoice} ? $invoice->{correctedInvoice} : "none",
    $invoice->{pdfUrl};

  foreach my $account_budget_summary (@{$invoice->{accountBudgetSummaries}}) {
    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",
      $account_budget_summary->{accountBudget},
      $account_budget_summary->{accountBudgetName}
      ? $account_budget_summary->{accountBudgetName}
      : "none",
      $account_budget_summary->{customer},
      $account_budget_summary->{customerDescriptiveName}
      ? $account_budget_summary->{customerDescriptiveName}
      : "none",
      $account_budget_summary->{purchaseOrderNumber}
      ? $account_budget_summary->{purchaseOrderNumber}
      : "none",
      $account_budget_summary->{billableActivityDateRange}{startDate},
      $account_budget_summary->{billableActivityDateRange}{endDate},
      $account_budget_summary->{subtotalAmountMicros},
      $account_budget_summary->{taxAmountMicros},
      $account_budget_summary->{totalAmountMicros};
  }
}get_invoices.pl

curl

بارگیری فاکتور PDF

هر صورت‌حسابی را می‌توان به‌صورت فایل PDF بارگیری کرد. وقتی Invoice را بازیابی کردید، باید درخواست HTTP برای نشانی وبی که در فیلد pdf_url آن ذخیره شده است ارسال کنید. این درخواست باید بااستفاده از همان «حساب Google» که برای بازیابی صورت‌حساب استفاده شده است اصالت‌سنجی شود؛ یعنی باید کد دسترسی OAuth تولیدشده بااستفاده از «حساب Google» را در سرایند درخواست Authorization: Bearer مشخص کنید:

curl --request GET \
     --header "Authorization: Bearer ACCESS_TOKEN" \
     "INVOICE_PDF_URL" > FILENAME.pdf

نتیجه، محتوای پی‌دی‌اف صورت‌حساب ذخیره‌شده در فایل <var>FILENAME</var>.pdf است.

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

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

قبلی

بودجه حساب

بعدی

مشوق‌ها (در فهرست مجازها)

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

پیش‌نیازها

بازیابی صورت‌حساب‌ها

جاوا

C#‎

PHP

Python

Ruby

پرل

curl

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

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

مبالغ را درک کنید

جاوا

C#‎

PHP

Python

Ruby

پرل

curl

بارگیری فاکتور PDF

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

صورت حساب‌ها