إعداد الفوترة

إعداد الفوترة هو رابط على مستوى الحساب بين حساب "إعلانات Google" وحساب "دفعات" (يُعرف أيضًا باسم إعداد الفاتورة)، ويحدّد بشكلٍ فعّال الشخص الذي يتم تحصيل الفواتير منه من خلال تكاليف حساب إعداد الفوترة. يقابل كل حساب دفعات فاتورة واحدة.

حول حسابات الدفعات

يحدد كل BillingSetup حسابًا على Payments يتم إصدار فواتير له بالتكاليف المستحقة على ميزانيات الحساب. يرتبط حساب الدفعات هذا بملف شخصي للدفع يكون مسؤولاً في النهاية عن تحصيل الرسوم.

تتضمّن إعدادات الفوترة كلاً من الحقل payments_account ومجموعة من حقول payments_account_info التي تحدّد أنّ حساب Payments قيد الاستخدام، بما في ذلك ما يلي:

• payments_account_info.payments_account_id: معرّف مكوّن من 16 رقمًا يُستخدم لتحديد حساب الدفعات المرتبط بإعداد الفوترة.
• payments_account_info.payments_account_name: اسم حساب الدفعات المرتبط بإعداد الفوترة. وتتم طباعة هذا الاسم على الفواتير الشهرية.
• payments_account_info.payments_profile_id: معرّف مكوّن من 12 رقمًا يُستخدم لتحديد الملف الشخصي للدفع المرتبط بإعداد الفوترة.

إذا كان حساب الدفعات مؤهلاً للفوترة الموحدة، يمكن تجميع حسابات إعلانات Google المتعددة في الفاتورة نفسها عن طريق تعيين إعدادات الفوترة لاستخدام حساب الدفعات الأساسي نفسه.

إنشاء إعدادات فوترة جديدة

يمكنك ربط إعدادات الفوترة الجديدة بحسابات الدفعات الحالية أو الحسابات التي تم إنشاؤها في الوقت نفسه.

استخدام حساب دفعات حالي

للربط بحساب دفعات حالي، اضبط payments_account على رقم تعريف المورد لحساب دفعات صالح. يُرجى عدم تعديل payments_account_info.

يمكنك إدراج حسابات الدفع المتاحة باستخدام PaymentsAccountService.ListPaymentsAccounts طريقة. تعتمد قيمة PaymentsAccounts التي يتم عرضها على الحساب الإداري الذي تستخدمه للمصادقة.

بالنسبة إلى كل PaymentsAccount، يظهر معرّف الحساب الإداري للدفع في الحقل paying_manager_customer.

استخدام حساب دفعات جديد

للربط بحساب دفعات جديد، اضبط الحقول التالية في payments_account_info (لا تضبط payments_account):

• payments_account_name
• payments_profile_id

ملاحظة: ستتم تعبئة كل من payments_account وpayments_account_info في عمليات الاسترداد اللاحقة لإعداد الفوترة.

يوضح المثال أدناه كيفية إنشاء إعداد فوترة جديد من معرّف ملف شخصي حالي لحساب الدفعات. كما هو موضّح أعلاه، سيؤدي ذلك أيضًا إلى إنشاء حساب دفعات جديد باسم My New Payments Account.

BillingSetup bsetup = BillingSetup.newBuilder()
    .setPaymentsAccountInfo(PaymentsAccountInfo.newBuilder()
        .setPaymentsAccountName("My New Payments Account")
        .setPaymentsProfileId("1234-5678-9012")
        .build())
    .setStartTimeType(TimeType.NOW)
    .build();

BillingSetupOperation op = BillingSetupOperation.newBuilder().setCreate(bsetup).build();

try (BillingSetupServiceClient billingSetupServiceClient = googleAdsClient
    .getBillingSetupServiceClient()) {

  MutateBillingSetupResponse response =
      billingSetupServiceClient.mutateBillingSetup(Long.toString(customerId), op);
}

وإذا كان هذا أول إعداد فوترة تتم إضافته إلى حساب على "إعلانات Google"، سيؤدي ذلك إلى تسجيل اشتراك العميل بفعالية في الفوترة باستخدام الملف الشخصي للدفع المرجع.

حالة إعداد الفوترة

تخضع مثيلات BillingSetup الجديدة للموافقة قبل أن تصبح سارية المفعول. وحتى ذلك الحين، تكون حالة status في PENDING.

يمكن أن يكون BillingSetup في أي مما يلي: status:

حالة إعداد الفوترة	الوصف
PENDING	في انتظار الموافقة.
APPROVED_HELD	تمت الموافقة عليه، إلا أن الميزانية المقابلة لم تتم الموافقة عليها. ولا يمكن أن يحدث ذلك إلا لإعدادات الفوترة التي تم ضبطها لنظام الفواتير الشهرية.
APPROVED	تمت الموافقة على الإعداد.
CANCELLED	تم إلغاء الإعداد بواسطة المستخدم قبل الموافقة.

استرداد إعداد فوترة الحساب

كما هو الحال مع معظم الكيانات الأخرى في إعلانات Google API، يتم جلب BillingSetup عن طريق طلب البحث عن GoogleAdsService.SearchStream باستخدام طلب البحث بلغة طلب البحث في "إعلانات Google" الذي يحدد الحقول المطلوب عرضها.

لغة Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  // Defines a GAQL query to retrieve all billing setup information.
  String searchQuery =
      "SELECT billing_setup.id, "
          + "  billing_setup.status, "
          + "  billing_setup.payments_account, "
          + "  billing_setup.payments_account_info.payments_account_id, "
          + "  billing_setup.payments_account_info.payments_account_name, "
          + "  billing_setup.payments_account_info.payments_profile_id, "
          + "  billing_setup.payments_account_info.payments_profile_name, "
          + "  billing_setup.payments_account_info.secondary_payments_profile_id "
          + "FROM billing_setup";

  // Creates a request that will retrieve all billing setups using pages of the specified
  // page size.
  SearchGoogleAdsRequest request =
      SearchGoogleAdsRequest.newBuilder()
          .setCustomerId(String.valueOf(customerId))
          .setPageSize(PAGE_SIZE)
          .setQuery(searchQuery)
          .build();

  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    // Issues the search request.
    SearchPagedResponse response = googleAdsServiceClient.search(request);

    // Iterates over all rows in all pages and prints the requested field values for the billing
    // setup in each row.
    for (GoogleAdsRow googleAdsRow : response.iterateAll()) {
      BillingSetup billingSetup = googleAdsRow.getBillingSetup();
      System.out.printf(
          "Billing setup with ID '%d', "
              + "status '%s', "
              + "payments_account '%s', "
              + "payments_account_id '%s', "
              + "payments_account_name '%s', "
              + "payments_profile_id '%s', "
              + "payments_profile_name '%s', "
              + "secondary_payments_profile_id '%s'.%n",
          billingSetup.getId(),
          billingSetup.getStatus(),
          billingSetup.getPaymentsAccount(),
          billingSetup.getPaymentsAccountInfo().getPaymentsAccountId(),
          billingSetup.getPaymentsAccountInfo().getPaymentsAccountName(),
          billingSetup.getPaymentsAccountInfo().getPaymentsProfileId(),
          billingSetup.getPaymentsAccountInfo().getPaymentsProfileName(),
          billingSetup.getPaymentsAccountInfo().getSecondaryPaymentsProfileId());
    }
  }
}
GetBillingSetup.java
      

#C

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsServiceClient.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V13.GoogleAdsService);

    // Define a GAQL query to retrieve all billing setup information.
    string searchQuery = @"
        SELECT
            billing_setup.id,
            billing_setup.status,
            billing_setup.payments_account,
            billing_setup.payments_account_info.payments_account_id,
            billing_setup.payments_account_info.payments_account_name,
            billing_setup.payments_account_info.payments_profile_id,
            billing_setup.payments_account_info.payments_profile_name,
            billing_setup.payments_account_info.secondary_payments_profile_id
        FROM billing_setup";

    // Creates a request that will retrieve all billing setups using pages of the specified
    // page size.
    SearchGoogleAdsRequest request = new SearchGoogleAdsRequest()
    {
        PageSize = PAGE_SIZE,
        Query = searchQuery,
        CustomerId = customerId.ToString()
    };

    try
    {
        PagedEnumerable<SearchGoogleAdsResponse, GoogleAdsRow> searchPagedResponse =
            googleAdsService.Search(request);

        foreach (GoogleAdsRow googleAdsRow in searchPagedResponse)
        {
            BillingSetup billingSetup = googleAdsRow.BillingSetup;
            Console.WriteLine($"Billing setup with ID '{billingSetup.Id}'has status " +
                $"'{billingSetup.Status}'.");

            // A missing billing setup will have no payments account information.
            if (billingSetup.HasPaymentsAccount)
            {
                Console.WriteLine(
                    $"\tPayments account: {billingSetup.PaymentsAccount}\n" +
                    "\tPayments account Id: " +
                    $"{billingSetup.PaymentsAccountInfo.PaymentsAccountId}\n" +
                    "\tPayments profile id: " +
                    $"{billingSetup.PaymentsAccountInfo.PaymentsProfileId}\n");

                // A pending billing setup will not have values for certain fields.
                if (billingSetup.Status != BillingSetupStatus.Pending)
                {
                    Console.WriteLine(
                        "\tPayments account name: " +
                        $"{billingSetup.PaymentsAccountInfo.PaymentsAccountName}\n" +
                        "\tPayments profile name: " +
                        $"{billingSetup.PaymentsAccountInfo.PaymentsProfileName}\n" +
                        "\tSecondary payments profile id: " +
                        $"{billingSetup.PaymentsAccountInfo.SecondaryPaymentsProfileId}");
                }
            }
            else
            {
                Console.WriteLine("Payments account details missing or incomplete.");
            }
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
GetBillingSetup.cs
      

لغة PHP

public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves the billing setups.
    $query = 'SELECT billing_setup.id, '
    . '  billing_setup.status, '
    . '  billing_setup.payments_account_info.payments_account_id, '
    . '  billing_setup.payments_account_info.payments_account_name, '
    . '  billing_setup.payments_account_info.payments_profile_id, '
    . '  billing_setup.payments_account_info.payments_profile_name, '
    . '  billing_setup.payments_account_info.secondary_payments_profile_id '
    . 'FROM billing_setup';

    // Issues a search request by specifying page size.
    $response =
        $googleAdsServiceClient->search($customerId, $query, ['pageSize' => self::PAGE_SIZE]);

    // Iterates over all rows in all pages and prints the requested field values for
    // the billing setup in each row.
    foreach ($response->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        $paymentAccountInfo = $googleAdsRow->getBillingSetup()->getPaymentsAccountInfo();
        if (is_null($paymentAccountInfo)) {
            printf(
                'Found the billing setup with ID %1$d, %3$s'
                . '  status \'%2$d\' with no payment account info. %3$s',
                $googleAdsRow->getBillingSetup()->getId(),
                $googleAdsRow->getBillingSetup()->getStatus(),
                PHP_EOL
            );
            continue;
        }
        printf(
            'Found the billing setup with ID %1$d, %8$s'
            . '  status \'%2$s\', %8$s'
            . '  payments account ID \'%3$s\', %8$s'
            . '  payments account name \'%4$s\', %8$s'
            . '  payments profile ID \'%5$s\', %8$s'
            . '  payments profile name \'%6$s\', %8$s'
            . '  secondary payments profile ID \'%7$s\'.%8$s',
            $googleAdsRow->getBillingSetup()->getId(),
            BillingSetupStatus::name($googleAdsRow->getBillingSetup()->getStatus()),
            $paymentAccountInfo->getPaymentsAccountId(),
            $paymentAccountInfo->getPaymentsAccountName(),
            $paymentAccountInfo->getPaymentsProfileId(),
            $paymentAccountInfo->getPaymentsProfileName(),
            $paymentAccountInfo->getSecondaryPaymentsProfileId()
                ? $paymentAccountInfo->getSecondaryPaymentsProfileId()
                : 'None',
            PHP_EOL
        );
    }
}
GetBillingSetup.php
      

لغة Python

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")

    query = """
        SELECT
          billing_setup.id,
          billing_setup.status,
          billing_setup.payments_account,
          billing_setup.payments_account_info.payments_account_id,
          billing_setup.payments_account_info.payments_account_name,
          billing_setup.payments_account_info.payments_profile_id,
          billing_setup.payments_account_info.payments_profile_name,
          billing_setup.payments_account_info.secondary_payments_profile_id
        FROM billing_setup"""

    stream = ga_service.search_stream(customer_id=customer_id, query=query)

    print("Found the following billing setup results:")
    for batch in stream:
        for row in batch.results:
            billing_setup = row.billing_setup
            pai = billing_setup.payments_account_info

            if pai.secondary_payments_profile_id:
                secondary_payments_profile_id = (
                    pai.secondary_payments_profile_id
                )
            else:
                secondary_payments_profile_id = "None"

            print(
                f"Billing setup with ID {billing_setup.id}, "
                f'status "{billing_setup.status.name}", '
                f'payments_account "{billing_setup.payments_account}" '
                f"payments_account_id {pai.payments_account_id}, "
                f'payments_account_name "{pai.payments_account_name}", '
                f"payments_profile_id {pai.payments_profile_id}, "
                f'payments_profile_name "{pai.payments_profile_name}", '
                "secondary_payments_profile_id "
                f"{secondary_payments_profile_id}."
            )
get_billing_setup.py
      

Ruby

def get_billing_setup(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  ga_service = client.service.google_ads

  search_query = <<~QUERY
    SELECT billing_setup.id,
      billing_setup.status,
      billing_setup.payments_account,
      billing_setup.payments_account_info.payments_account_id,
      billing_setup.payments_account_info.payments_account_name,
      billing_setup.payments_account_info.payments_profile_id,
      billing_setup.payments_account_info.payments_profile_name,
      billing_setup.payments_account_info.secondary_payments_profile_id
    FROM billing_setup
  QUERY

  response = ga_service.search(
    customer_id: customer_id,
    query: search_query,
    page_size: PAGE_SIZE,
  )

  response.each do |row|
    billing_setup = row.billing_setup
    payments_account_info = billing_setup.payments_account_info

    puts sprintf('Billing setup with ID "%s", status "%s",'\
        ' payments_account "%s", payments_account_id "%s",'\
        ' payments_account_name "%s", payments_profile_id "%s",'\
        ' payments_profile_name "%s", secondary_payments_profile_id "%s"',
        billing_setup.id,
        billing_setup.status,
        billing_setup.payments_account,
        payments_account_info ? payments_account_info.payments_account_id : "N/A",
        payments_account_info ? payments_account_info.payments_account_name : "N/A",
        payments_account_info ? payments_account_info.payments_profile_id : "N/A",
        payments_account_info ? payments_account_info.payments_profile_name : "N/A",
        payments_account_info ? payments_account_info.secondary_payments_profile_id : "N/A"
    )
  end
end
get_billing_setup.rb
      

Perl

sub get_billing_setup {
  my ($api_client, $customer_id) = @_;

  # Create a query that retrieves the billing setups.
  my $search_query =
    "SELECT billing_setup.id, billing_setup.status, " .
    "billing_setup.payments_account, " .
    "billing_setup.payments_account_info.payments_account_id, " .
    "billing_setup.payments_account_info.payments_account_name, " .
    "billing_setup.payments_account_info.payments_profile_id, " .
    "billing_setup.payments_account_info.payments_profile_name, " .
    "billing_setup.payments_account_info.secondary_payments_profile_id " .
    "FROM billing_setup";

  # Create a search Google Ads request that will retrieve the billing setups
  # using pages of the specified page size.
  my $search_request =
    Google::Ads::GoogleAds::V13::Services::GoogleAdsService::SearchGoogleAdsRequest
    ->new({
      customerId => $customer_id,
      query      => $search_query,
      pageSize   => PAGE_SIZE
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $iterator = Google::Ads::GoogleAds::Utils::SearchGoogleAdsIterator->new({
    service => $google_ads_service,
    request => $search_request
  });

  # Iterate over all rows in all pages and print the requested field values for
  # the billing setup in each row.
  while ($iterator->has_next) {
    my $google_ads_row = $iterator->next;

    my $billing_setup        = $google_ads_row->{billingSetup};
    my $payment_account_info = $billing_setup->{paymentsAccountInfo};

    if (!$payment_account_info) {
      printf "Found the billing setup with ID %d, status '%s' " .
        "with no payment account info.\n", $billing_setup->{id},
        $billing_setup->{status};
      next;
    }

    printf "Found the billing setup with ID %d, status '%s', " .
      "payments account '%s', " .
      "payments account ID '%s', payments account name '%s', " .
      "payments profile ID '%s', payments profile name '%s', " .
      "secondary payments profile ID '%s'.\n",

      $billing_setup->{id}, $billing_setup->{status},
      $billing_setup->{paymentsAccount},
      $payment_account_info->{paymentsAccountId},
      $payment_account_info->{paymentsAccountName},
      $payment_account_info->{paymentsProfileId},
      $payment_account_info->{paymentsProfileName},
      $payment_account_info->{secondaryPaymentsProfileId}
      ? $payment_account_info->{secondaryPaymentsProfileId}
      : "None";
  }

  return 1;
}
get_billing_setup.pl
      

بعد الحصول على مرجع إلى BillingSetup، يمكنك استخدامه لإنشاء AccountBudgetProposal كما هو موضّح في ميزانية الحساب.

إلغاء إعداد فوترة معلّق

يمكن إلغاء BillingSetup التي لم تدخل حيز التنفيذ بعد باستخدام عملية الإزالة. لا يمكن إلغاء إعدادات الفوترة إلا إذا كانت status هي PENDING أو إذا كانت APPROVED تبدأ في وقت لاحق.

لغة Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId, long billingSetupId) {
  // Formats the customerId and billingSetupId into a resource name.
  String billingSetupResourceName = ResourceNames.billingSetup(customerId, billingSetupId);

  // Constructs an operation that will remove the billing setup.
  BillingSetupOperation operation =
      BillingSetupOperation.newBuilder().setRemove(billingSetupResourceName).build();

  try (BillingSetupServiceClient billingSetupServiceClient =
      googleAdsClient.getLatestVersion().createBillingSetupServiceClient()) {
    // Sends the operation in a mutate request.
    MutateBillingSetupResponse response =
        billingSetupServiceClient.mutateBillingSetup(String.valueOf(customerId), operation);

    System.out.printf(
        "Removed billing setup with resource name '%s'.%n",
        response.getResult().getResourceName());
  }
}
RemoveBillingSetup.java
      

#C

public void Run(GoogleAdsClient client, long customerId, long billingSetupId)
{
    // Get the BillingSetupServiceClient.
    BillingSetupServiceClient billingSetupService = client.GetService(
        Services.V13.BillingSetupService);

    // Create the billing setup resource.
    String billingSetupResource = ResourceNames.BillingSetup(customerId, billingSetupId);

    // Construct an operation that will remove the billing setup.
    BillingSetupOperation operation = new BillingSetupOperation()
    {
        Remove = billingSetupResource
    };

    try
    {
        // Send the operation in a mutate request.
        MutateBillingSetupResponse response =
            billingSetupService.MutateBillingSetup(customerId.ToString(), operation);

        Console.WriteLine("Removed billing setup with resource name '{0}'.",
            response.Result.ResourceName);
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
RemoveBillingSetup.cs
      

لغة PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $billingSetupId
) {
    // Creates the resource name of a billing setup to remove.
    $billingSetupResourceName = ResourceNames::forBillingSetup($customerId, $billingSetupId);

    // Creates a billing setup operation.
    $billingSetupOperation = new BillingSetupOperation();
    $billingSetupOperation->setRemove($billingSetupResourceName);

    // Issues a mutate request to remove the billing setup.
    $billingSetupServiceClient = $googleAdsClient->getBillingSetupServiceClient();
    $response =
        $billingSetupServiceClient->mutateBillingSetup($customerId, $billingSetupOperation);

    /** @var BillingSetup $removedBillingSetup */
    $removedBillingSetup = $response->getResult();
    printf(
        "Removed billing setup with resource name '%s'%s",
        $removedBillingSetup->getResourceName(),
        PHP_EOL
    );
}
RemoveBillingSetup.php
      

لغة Python

def main(client, customer_id, billing_setup_id):
    billing_setup_service = client.get_service("BillingSetupService")

    # Create billing setup operation.
    billing_setup_operation = client.get_type("BillingSetupOperation")
    billing_setup_operation.remove = billing_setup_service.billing_setup_path(
        customer_id, billing_setup_id
    )

    # Remove the billing setup.
    billing_setup_response = billing_setup_service.mutate_billing_setup(
        customer_id=customer_id, operation=billing_setup_operation
    )
    print(
        "Removed billing setup "
        f'"{billing_setup_response.results[0].resource_name}"'
    )
remove_billing_setup.py
      

Ruby

def remove_billing_setup(customer_id, billing_setup_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  billing_setup_service = client.service.billing_setup

  resource =  client.path.billing_setup(customer_id, billing_setup_id)
  operation = client.operation.remove_resource.billing_setup(resource)

  response = billing_setup_service.mutate_billing_setup(
    customer_id: customer_id,
    operation: operation,
  )

  puts sprintf("Removed billing_setup %s", response.results.first.resource_name)
end
remove_billing_setup.rb
      

Perl

sub remove_billing_setup {
  my ($api_client, $customer_id, $billing_setup_id) = @_;

  # Create the resource name of a billing setup to remove.
  my $billing_setup_resource_name =
    Google::Ads::GoogleAds::V13::Utils::ResourceNames::billing_setup(
    $customer_id, $billing_setup_id);

  # Create a billing setup operation.
  my $billing_setup_operation =
    Google::Ads::GoogleAds::V13::Services::BillingSetupService::BillingSetupOperation
    ->new({
      remove => $billing_setup_resource_name
    });

  # Remove the billing setup.
  my $billing_setup_response = $api_client->BillingSetupService->mutate({
    customerId => $customer_id,
    operation  => $billing_setup_operation
  });

  printf "Removed billing setup with resource name: '%s'.\n",
    $billing_setup_response->{result}{resourceName};

  return 1;
}
remove_billing_setup.pl