Crear una cuenta

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 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 superior directa en la que se crea la cuenta de cliente nueva.
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 superior en 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: Es el 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 en 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 la operación se realiza correctamente, CreateCustomerClient muestra un CreateCustomerClientResponse que contiene el resource_name (customers/{new_customer_id}) de la cuenta recién creada (además de un invitation_link si email_address y access_role fueron incluidos por una cuenta de administrador de 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 de usuario, 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 al new_customer_id recién creado con MutateCustomerUserAccessInvitation en CustomerUserAccessInvitationService. Cuando te autentiques a través de la cuenta de administrador superior, 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 mostrar los siguientes errores:

  • CustomerError: Indica restricciones de creación a nivel de la cuenta, como CREATION_DENIED_INELIGIBLE_MCC (la cuenta de administrador no es apta para crear cuentas nuevas) o CREATION_DENIED_FOR_POLICY_VIOLATION (se rechaza la creación del cliente debido a un incumplimiento de política).
  • ManagerLinkError: Indica restricciones de jerarquía o límites de la cuenta, como TOO_MANY_ACCOUNTS, TOO_MANY_ACCOUNTS_AT_MANAGER o MAX_DEPTH_EXCEEDED.
  • AccessInvitationError: Se muestra si se proporciona un email_address opcional (junto con access_role, disponible solo para las cuentas de la lista de entidades permitidas) en CreateCustomerClientRequest para invitar a un usuario a la cuenta nueva y la invitación falla (por ejemplo, INVALID_EMAIL_ADDRESS, GOOGLE_CONSUMER_ACCOUNT_NOT_ALLOWED o EMAIL_DOMAIN_POLICY_VIOLATED). Las cuentas que no están en la lista de entidades permitidas deben invitar a los usuarios después de la creación de la cuenta con CustomerUserAccessInvitationService.
  • CurrencyCodeError.UNSUPPORTED o TimeZoneError.INVALID_TIME_ZONE: Se muestra cuando el currency_code o time_zone especificado en el objeto Customer no es válido o no es compatible.