إعداد الفوترة هو رابط على مستوى الحساب بين حساب على "إعلانات Google" وحساب الدفعات (يُعرف أيضًا باسم إعداد فاتورة)، والذي يحدِّد بشكل فعّال الجهة التي سيتم تحرير فواتير لها عن التكاليف التي تتحملها ميزانيات حساب الفوترة. يتطابق كل حساب دفعات مع فاتورة واحدة.
لمحة عن حسابات الدفعات
يحدِّد كل BillingSetup
حساب دفعات
يتم إصدار فواتير له عن التكاليف الناتجة عن ميزانيات حسابه. يرتبط حساب الدفعات هذا بملف شخصي للدفع مسؤول عن الرسوم.
تحتوي إعدادات الفوترة على حقل payments_account
ومجموعة من الحقول
payments_account_info
التي تحدّد حساب الدفعات قيد الاستخدام، بما في ذلك ما يلي:
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
):
يوضّح المثال التالي كيفية إنشاء إعداد فوترة جديد من معرّف ملف شخصي حالي للدفع. كما هو موضّح أعلاه، سيؤدي ذلك أيضًا إلى إنشاء حساب جديد للدفع
يحمل الاسم 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 Ads 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()); } } }
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; } }
2,999
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 ); } }
لغة 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}." )
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
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; }
بعد الحصول على مرجع إلى 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()); } }
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; } }
2,999
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 ); }
لغة 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}"' )
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
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; }