صورتحساب

فاکتورهای ماهانه برای یک حساب گوگل ادز را می‌توان با استفاده از 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()));
      

سی شارپ

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

پی اچ پی

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

پایتون

# 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(),
)
      

روبی

# 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,
)
      

پرل

# 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))});
      

حلقه زدن

# 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}"
      

پاسخ یک شیء 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 $قبل از مالیات + $
هزینه‌های نظارتی قبل از کسر مالیات + $
هزینه صادرات\پیش پرداخت\صادرات + $
مالیات

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

جاوا

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

سی شارپ

// 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));
    }
}
      

پی اچ پی

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

پایتون

    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)}'
                """
            )
      

روبی

# 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
end
      

پرل

# 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};
  }
}
      

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

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

curl --request GET \
     --header "Authorization: Bearer access token" \
     Invoice.pdf_url > filename.pdf

نتیجه، محتوای PDF فاکتور است که در فایل filename.pdf ذخیره می‌شود.

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

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