Faturalar

Google Ads hesabının aylık faturaları InvoiceService kullanılarak alınabilir.

Ön koşullar

• Google Ads hesabında aylık faturalandırma etkin olmalıdır. Google Ads API'yi kullanarak faturalandırmayı nasıl yöneteceğinizi öğrenmek için hesap faturalandırma ayarları ve bütçeler ile ilgili kılavuzları inceleyin.
• Ayarlanırsa login-customer-id, faturalarını aldığınız Google Ads hesabını yöneten bir yönetici hesabının müşteri kimliğini belirtmelidir. Bu, Google Ads kullanıcı arayüzünde ödeme yöneticisi olarak etiketlenir.

Faturaları alma

Önemli: 1 Ocak 2019'dan önce düzenlenen faturaları talep edemezsiniz.

Faturaları almak için ListInvoicesRequest içindeki tüm zorunlu alanları ayarlayarak InvoiceService.ListInvoices yöntemini istemeniz gerekir:

• customer_id: Google Ads reklam sunma hesabının müşteri kimliği.
• billing_setup: customers/{customer_id}/billingSetups/{billing_setup_id} biçimindeki faturalandırma kurulumu kaynak adı.
• issue_year: Dört basamaklı bir dize olarak düzenleme yılı (ör. "2025").
• issue_month: Düzenlendiği ay için MonthOfYear enum değeri.

Aşağıdaki isteğe bağlı alanı da ayarlayabilirsiniz:

• include_granular_level_invoice_details: İsteğe bağlı Boole değeri (varsayılan olarak false). true olarak ayarlandığında, döndürülen Invoice nesneleri kampanya düzeyinde maliyet dökümlerini (AccountBudgetSummary.campaign_summaries), ayrıntılı düzenleme maliyetlerini (AccountSummary.regulatory_cost_summaries) ve ayrıntılı düzenlemeleri (AccountSummary.adjustment_summaries) içerir.

Birleştirilmiş faturalandırma ayarlarınız varsa Google Ads API, yalnızca API isteğinde belirtilen customer_id için değil, aynı faturalandırma ayarlarını kullanan tüm müşteriler için faturaları döndürür.

customer_id, bir Google Ads reklam sunma hesabı olmalıdır. Ödeme yöneticisinin tüm faturalarını almak için Google Ads reklam sunma hesabı başına bir istek gönderin.

Örnek:

Java

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

Perl

# 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
      

Yanıt, eşleşen Invoice nesnelerinin listesini içeren bir ListInvoicesResponse nesnesidir. Bu nesnelerin her biri, aşağıdakiler gibi geniş bir alan grubu içerir:

• Kimlikler: payments_account_id, payments_profile_id.
• Zaman: issue_date, due_date, service_date_range.
• Tutarlar: subtotal_amount_micros, tax_amount_micros, total_amount_micros.
• PDF: pdf_url. Talimatlar için Fatura PDF'si indirme başlıklı makaleyi inceleyin.
• Geçmiş: corrected_invoice, replaced_invoices.

Ayrıca, alakalı olduğunda diğer belirli alanları da içerir:

• Düzenlemeler: adjustments_subtotal_amount_micros, adjustments_tax_amount_micros, adjustments_total_amount_micros.
• Yasal düzenleme maliyetleri: regulatory_costs_subtotal_amount_micros, regulatory_costs_tax_amount_micros, regulatory_costs_total_amount_micros.
• İhracat ücretleri: export_charge_subtotal_amount_micros, export_charge_tax_amount_micros, export_charge_total_amount_micros.

Önemli: Fatura, istenen faturalandırma ayarı tarafından kullanılan temel ödeme hesabını kullanan faturalandırma ayarlarına sahip tüm Google Ads hesaplarının verilerini birleştirir. Bu durum yalnızca temel ödeme hesabı birleştirilmiş faturalandırma için uygun olduğunda gerçekleşir.

Bütçe ayrıntılarını alma

Invoice, account_budget_summaries alanında AccountBudgetSummary nesnelerinin listesi olarak ilgili hesap bütçeleri hakkında ayrıntılı bilgi sağlar:

• Kimlikler ve meta veriler: customer, customer_descriptive_name, account_budget, account_budget_name, purchase_order_number.
• Zaman: billable_activity_date_range.
• Tutarlar: subtotal_amount_micros, tax_amount_micros, total_amount_micros, invalid_activity_amount_micros, billed_amount_micros, served_amount_micros, overdelivery_amount_micros.
• Geçersiz etkinlik dökümleri: invalid_activity_summaries, original_month_of_service, original_year_of_service, original_invoice_id, original_account_budget_name, original_purchase_order_number ve amount_micros içeren InvalidActivitySummary nesnelerinin listesi.
• Kampanya düzeyinde dökümler (include_granular_level_invoice_details, true olduğunda doldurulur): campaign_summaries, campaign_description, quantity, unit_of_measure (UnitOfMeasure) ve amount_micros içeren CampaignSummary nesnelerinin listesi.

Hesap ayrıntılarını alma

Invoice, account_summaries alanında AccountSummary nesnelerinin listesi olarak ilgili hesaplar hakkında bilgi sağlar. Bu bölümde faturalandırma düzeltmeleri, kupon düzenlemeleri, fazla kredi düzenlemeleri, ihracat ücretleri ve yasal düzenleme maliyetleri için hesap düzeyinde ara toplam, vergi ve toplam tutarlar yer alır.

ListInvoicesRequest içinde include_granular_level_invoice_details değerini true olarak ayarlamak, her AccountSummary için aşağıdaki döküm listelerini de doldurur:

• regulatory_cost_summaries: regulatory_fee_type (RegulatoryFeeType) ve amount_micros içeren RegulatoryCostSummary nesnelerinin listesi.
• adjustment_summaries: adjustment_description ve amount_micros içeren AdjustmentSummary nesnelerinin listesi.

Tutarları anlama

Önemli: Faturalardaki tutarlar ile yayınlama metrikleri veya hesap bütçeleri arasındaki farklar yaygındır ve beklenen bir durumdur. Bunun nedeni, daha önce düzenlenmiş faturalarda dikkate alınmayan geç düzenlemelerdir.

AccountBudgetSummary, AccountSummary ve Invoice nesnelerinde sağlanan tüm tutarlar, hizmet dönemleri boyunca ilişkilendirilebilir ve şu kurallara göre değerlendirilir:

AccountBudgetSummary	Değerlendirme kuralı
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	Değerlendirme kuralı
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	Değerlendirme kuralı
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$

Alınan faturaların nasıl yinelenebileceğine dair bir örneği aşağıda bulabilirsiniz:

Java

// 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
end
get_invoices.rb
      

Perl

# 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

Not: Bu adım için doğrudan bir REST kod örneği sağlanmamış olsa da bunu manuel bir REST isteği kullanarak gerçekleştirebilirsiniz.

Google Ads API REST arayüzü belgelerine ve yönteme özel referans sayfalarına bakın. JSON yükünü proto tanımlarına göre oluşturmanız gerekir.

Önemli Kaynaklar:

• REST'i kullanma
• REST Arayüzü Yapısı
• JSON Alan Eşlemeleri
• Belirli bir hizmet ve yöntem için REST API referansına bakın.

Fatura PDF'si indirme

Tüm faturalar PDF dosyası olarak indirilebilir. Invoice nesnesini aldıktan sonra, pdf_url alanında depolanan URL için bir HTTP isteği göndermeniz gerekir. Bu isteğin kimliği, faturayı almak için kullanılan Google Hesabı ile doğrulanmalıdır. Diğer bir deyişle, Authorization: Bearer istek başlığında Google Hesabı kullanılarak oluşturulan bir OAuth erişim jetonu belirtmeniz gerekir:

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

Sonuç, dosyada depolanan bir fatura PDF içeriğidir <var>FILENAME</var>.pdf.

Yaygın hata kodları

Senaryo	Hata Kodu
Faturalandırma ayarı, düzenlendiği yıl veya düzenlendiği ay eksik ya da boş.	RequestError.REQUIRED_FIELD_MISSING
Belirtilen faturalandırma ayarı, düzenlendiği yıl veya düzenlendiği ay ayrıştırılamıyor.	FieldError.INVALID_VALUE
İstek, 1 Ocak 2019'dan önce düzenlenen faturalar için yapılmıştır.	InvoiceError.YEAR_MONTH_TOO_OLD
İstek, fatura almayan bir müşteri için gönderilmiştir.	InvoiceError.NOT_INVOICED_CUSTOMER
Kullanıcının faturalandırma ayarının faturalarını görüntüleme izni yok.	AuthorizationError.ACTION_NOT_PERMITTED