Para crear una cuenta de cliente nueva, envía un objeto Customer prepropagado con el método CreateCustomerClient en CustomerService.
A diferencia de la creación de entidades estándar (como la creación de campañas con llamadas a mutate), debes especificar el ID de cliente de la cuenta de administrador en la solicitud, en lugar del ID del cliente que se está creando.
Campos de solicitud y cliente
Cuando llames a CustomerService.CreateCustomerClient, configura
CreateCustomerClientRequest y su objeto Customer anidado como
se muestra en la siguiente tabla:
| Campo o encabezado | Requisito | Mutabilidad y descripción |
|---|---|---|
customer_id |
Obligatorio | Es el ID de cliente de 10 dígitos (sin guiones) de la cuenta de administrador principal directa en la que se crea la nueva cuenta de cliente. |
login-customer-id (encabezado) |
Condicional | Es obligatorio en los encabezados de la solicitud si el usuario autenticado accede a la cuenta de administrador superior (customer_id) a través de una cuenta de administrador principal que se encuentra en un nivel más alto de la jerarquía. |
customer_client.descriptive_name |
Obligatorio | Mutable: Es el nombre visible de la cuenta nueva (por ejemplo, "Acct Created with CustomerService"). Se puede actualizar más adelante con CustomerService.MutateCustomer. |
customer_client.currency_code |
Obligatorio | Inmutable después de la creación: Código de moneda de facturación ISO 4217 de 3 caracteres (por ejemplo, USD o EUR). Consulta los códigos de moneda admitidos. |
customer_client.time_zone |
Obligatorio | Inmutable después de la creación: Es el ID de la zona horaria de la cuenta (por ejemplo, America/New_York). Consulta las zonas horarias admitidas. |
email_address y access_role |
Opcional (solo para la lista de entidades permitidas) | Invita a un usuario (ADMIN, STANDARD, READ_ONLY o EMAIL_ONLY) a la cuenta creada durante la creación. Las cuentas que no estén en la lista de entidades permitidas deben invitar a los usuarios después de la creación con CustomerUserAccessInvitationService. |
validate_only |
Opcional | Cuando es true, valida los parámetros de la solicitud y la elegibilidad del administrador sin crear la cuenta. |
Ejemplo de código
En el siguiente ejemplo, se muestra cómo crear una cuenta de cliente en una cuenta de administrador existente:
Java
private void runExample(GoogleAdsClient googleAdsClient, Long managerId) { // Formats the current date/time to use as a timestamp in the new customer description. String dateTime = ZonedDateTime.now().format(DateTimeFormatter.RFC_1123_DATE_TIME); // Initializes a Customer object to be created. Customer customer = Customer.newBuilder() .setDescriptiveName("Account created with CustomerService on '" + dateTime + "'") .setCurrencyCode("USD") .setTimeZone("America/New_York") // Optional: Sets additional attributes of the customer. .setTrackingUrlTemplate("{lpurl}?device={device}") .setFinalUrlSuffix("keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}") .build(); // Sends the request to create the customer. try (CustomerServiceClient client = googleAdsClient.getLatestVersion().createCustomerServiceClient()) { CreateCustomerClientResponse response = client.createCustomerClient(managerId.toString(), customer); System.out.printf( "Created a customer with resource name '%s' under the manager account with" + " customer ID '%d'.%n", response.getResourceName(), managerId); } }
C#
public void Run(GoogleAdsClient client, long managerCustomerId) { // Get the CustomerService. CustomerServiceClient customerService = client.GetService(Services.V26.CustomerService); Customer customer = new Customer() { DescriptiveName = $"Account created with CustomerService on '{DateTime.Now}'", // For a list of valid currency codes and time zones see this documentation: // https://developers.google.com/google-ads/api/reference/data/codes-formats#codes_formats. CurrencyCode = "USD", TimeZone = "America/New_York", // The below values are optional. For more information about URL // options see: https://support.google.com/google-ads/answer/6305348. TrackingUrlTemplate = "{lpurl}?device={device}", FinalUrlSuffix = "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}" }; try { // Create the account. CreateCustomerClientResponse response = customerService.CreateCustomerClient( managerCustomerId.ToString(), customer); // Display the result. Console.WriteLine($"Created a customer with resource name " + $"'{response.ResourceName}' under the manager account with customer " + $"ID '{managerCustomerId}'"); } catch (GoogleAdsException e) { Console.WriteLine("Failure:"); Console.WriteLine($"Message: {e.Message}"); Console.WriteLine($"Failure: {e.Failure}"); Console.WriteLine($"Request ID: {e.RequestId}"); throw; } }
PHP
public static function runExample(GoogleAdsClient $googleAdsClient, int $managerCustomerId) { $customer = new Customer([ 'descriptive_name' => 'Account created with CustomerService on ' . date('Ymd h:i:s'), // For a list of valid currency codes and time zones see this documentation: // https://developers.google.com/google-ads/api/reference/data/codes-formats. 'currency_code' => 'USD', 'time_zone' => 'America/New_York', // The below values are optional. For more information about URL // options see: https://support.google.com/google-ads/answer/6305348. 'tracking_url_template' => '{lpurl}?device={device}', 'final_url_suffix' => 'keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}' ]); // Issues a mutate request to create an account $customerServiceClient = $googleAdsClient->getCustomerServiceClient(); $response = $customerServiceClient->createCustomerClient( CreateCustomerClientRequest::build($managerCustomerId, $customer) ); printf( 'Created a customer with resource name "%s" under the manager account with ' . 'customer ID %d.%s', $response->getResourceName(), $managerCustomerId, PHP_EOL ); }
Python
def main(client: GoogleAdsClient, manager_customer_id: str) -> None: """The main method that creates all necessary entities for the example. Args: client: an initialized GoogleAdsClient instance. manager_customer_id: a manager client customer ID. """ customer_service: CustomerServiceClient = client.get_service( "CustomerService" ) customer: Customer = client.get_type("Customer") now: str = datetime.today().strftime("%Y%m%d %H:%M:%S") customer.descriptive_name = f"Account created with CustomerService on {now}" # For a list of valid currency codes and time zones see this documentation: # https://developers.google.com/google-ads/api/reference/data/codes-formats customer.currency_code = "USD" customer.time_zone = "America/New_York" # The below values are optional. For more information about URL # options see: https://support.google.com/google-ads/answer/6305348 customer.tracking_url_template = "{lpurl}?device={device}" customer.final_url_suffix = ( "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}" ) response: CreateCustomerClientResponse = ( customer_service.create_customer_client( customer_id=manager_customer_id, customer_client=customer ) ) print( f'Customer created with resource name "{response.resource_name}" ' f'under manager account with ID "{manager_customer_id}".' )
Ruby
def create_customer(manager_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 customer = client.resource.customer do |c| c.descriptive_name = "Account created with CustomerService on #{(Time.new.to_f * 1000).to_i}" # For a list of valid currency codes and time zones, see this documentation: # https://developers.google.com/google-ads/api/reference/data/codes-formats c.currency_code = "USD" c.time_zone = "America/New_York" # The below values are optional. For more information about URL options, see: # https://support.google.com/google-ads/answer/6305348 c.tracking_url_template = "{lpurl}?device={device}" c.final_url_suffix = "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}" end response = client.service.customer.create_customer_client( customer_id: manager_customer_id, customer_client: customer ) puts "Created a customer with resource name #{response.resource_name} under" + " the manager account with customer ID #{manager_customer_id}." end
Perl
sub create_customer { my ($api_client, $manager_customer_id) = @_; # Initialize a customer to be created. my $customer = Google::Ads::GoogleAds::V26::Resources::Customer->new({ descriptiveName => "Account created with CustomerService on #" . uniqid(), # For a list of valid currency codes and time zones, see this documentation: # https://developers.google.com/google-ads/api/reference/data/codes-formats currencyCode => "USD", timeZone => "America/New_York", # The below values are optional. For more information about URL options, see: # https://support.google.com/google-ads/answer/6305348 trackingUrlTemplate => "{lpurl}?device={device}", finalUrlSuffix => "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}" }); # Create the customer client. my $create_customer_client_response = $api_client->CustomerService()->create_customer_client({ customerId => $manager_customer_id, customerClient => $customer }); printf "Created a customer with resource name '%s' under the manager account " . "with customer ID %d.\n", $create_customer_client_response->{resourceName}, $manager_customer_id; return 1; }
curl
# Creates a customer client. # # Variables: # API_VERSION, # MANAGER_CUSTOMER_ID, # OAUTH2_ACCESS_TOKEN: # See https://developers.google.com/google-ads/api/rest/auth#request_headers # for details. # curl -f --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "customerClient": { "descriptiveName": "Account created with CustomerService #${RANDOM}", "currencyCode": "USD", "timeZone": "America/New_York" } } EOF
Respuesta y próximos pasos
Si se ejecuta correctamente, CreateCustomerClient devuelve un CreateCustomerClientResponse que contiene el resource_name (customers/{new_customer_id}) de la cuenta recién creada (además de un invitation_link si una cuenta de administrador incluyó email_address y access_role en la lista de entidades permitidas). Luego, puedes usar este
nombre de recurso o ID de cliente para verificar la cuenta en tu jerarquía, otorgar acceso
a los usuarios, configurar la facturación o propagar campañas.
Verifica la cuenta creada en la jerarquía de administrador
Consulta el recurso customer_client en la cuenta de administrador (customer_id) con GoogleAdsService.SearchStream para inspeccionar la cuenta secundaria recién creada:
SELECT
customer_client.id,
customer_client.resource_name,
customer_client.client_customer,
customer_client.descriptive_name,
customer_client.currency_code,
customer_client.time_zone,
customer_client.manager,
customer_client.level,
customer_client.status
FROM customer_client
WHERE customer_client.level = 1
AND customer_client.id = {new_customer_id}
Invita a usuarios a la cuenta nueva
Si tu cuenta de administrador no está en la lista de entidades permitidas para configurar email_address y access_role directamente en CreateCustomerClientRequest, envía una invitación de acceso a la new_customer_id recién creada con MutateCustomerUserAccessInvitation en CustomerUserAccessInvitationService. Cuando te autentiques a través de la
cuenta de administrador principal, incluye login-customer-id: {manager_customer_id} en
los encabezados de la solicitud HTTP:
POST https://googleads.googleapis.com/v26/customers/{new_customer_id}/customerUserAccessInvitations:mutate
{
"operation": {
"create": {
"emailAddress": "user@example.com",
"accessRole": "ADMIN"
}
}
}
Manejo de errores
Las llamadas a CreateCustomerClient pueden devolver los siguientes errores:
CustomerError: Indica las restricciones de creación a nivel de la cuenta, comoCREATION_DENIED_INELIGIBLE_MCC(la cuenta de administrador no es apta para crear cuentas nuevas) oCREATION_DENIED_FOR_POLICY_VIOLATION(se rechaza la creación de clientes debido a un incumplimiento de política).ManagerLinkError: Indica restricciones de jerarquía o de límite de la cuenta, comoTOO_MANY_ACCOUNTS,TOO_MANY_ACCOUNTS_AT_MANAGERoMAX_DEPTH_EXCEEDED.AccessInvitationError: Se muestra si se proporciona unemail_addressopcional (junto conaccess_role, disponible solo para las cuentas de la lista de entidades permitidas) enCreateCustomerClientRequestpara invitar a un usuario a la cuenta nueva y la invitación falla (por ejemplo,INVALID_EMAIL_ADDRESS,GOOGLE_CONSUMER_ACCOUNT_NOT_ALLOWEDoEMAIL_DOMAIN_POLICY_VIOLATED). Las cuentas que no están en la lista de entidades permitidas deben invitar a los usuarios después de crear la cuenta conCustomerUserAccessInvitationService.CurrencyCodeError.UNSUPPORTEDoTimeZoneError.INVALID_TIME_ZONE: Se muestra cuando elcurrency_codeotime_zoneespecificado en el objetoCustomerno es válido o no es compatible.