API de Android Developer Console

La API de Android Developer Console es un servicio RESTful que permite a los desarrolladores verificados automatizar los flujos de trabajo de la verificación de desarrolladores de Android en Android Developer Console, lo que incluye recuperar cuentas de desarrollador, comprobar los requisitos de elegibilidad clave, registrar nombres de paquetes de Android, registrar claves de firma de apps y verificar la propiedad de las claves.

Descripción general, casos de uso y contexto de implementación

Casos de uso y funciones clave

• Registro automatizado de nombres de paquetes de CI/CD: Registra decenas o cientos de nombres de paquetes de Android de forma programática (CreateAndroidPackage).
• Inspección previa de la política de claves históricas: Inspecciona de forma programática si Google observó anteriormente un nombre de paquete en el ecosistema y si el registro de un certificado de firma específico requiere la verificación de la propiedad de la clave (GetAndroidPackageRegistrationPolicy).
• Registro automatizado de la clave de firma de la app y verificación de propiedad: Registra las huellas digitales SHA-256 del certificado de firma público (CreateAndroidPackageKey), recupera tokens de desafío de verificación únicos (verificationToken) y automatiza la prueba de posesión de la clave privada con las cargas de APK firmadas de solicitud única o reanudables (VerifyAndroidPackageKeyOwnership).
• Envío de justificación programática: Envía justificaciones de propiedad (JustifyAndroidPackageKeyRegistration).
• Supervisión de estado: Supervisa el estado de registro en las cuentas de desarrollador, los nombres de paquetes y las claves de firma de la app (GetDeveloperAccount, ListDeveloperAccounts, GetAndroidPackage, ListAndroidPackages, GetAndroidPackageKey, ListAndroidPackageKeys).

Flujo de trabajo de implementación de extremo a extremo

1. Verifica la identidad del desarrollador una vez en la IU: Completa la verificación de identidad del desarrollador (INDIVIDUAL o ORGANIZATION) en Android Developer Console para que verificationState sea VERIFIED.
2. Habilita la API y autentica: Habilita androiddeveloperconsole.googleapis.com en tu proyecto de Google Cloud y obtén un token de acceso del portador de OAuth 2.0 delegado por el usuario con el permiso https://www.googleapis.com/auth/androiddeveloperconsole.
3. Descubre el nombre del recurso de tu cuenta de desarrollador: Llama a GET /v1/developerAccounts (ListDeveloperAccounts) para recuperar developerAccounts/{developer_account} y verificar que verificationState sea VERIFIED.
4. Verifica la política de registro para el nombre del paquete: Llama a GET /v1/developerAccounts/{id}/androidPackages/{pkg}/registrationPolicy (GetAndroidPackageRegistrationPolicy) para inspeccionar keySelectionStrategy (SELECT_KEY_FROM_LIST o USE_ANY_KEY) y cualquier clave de firma histórica conocida (knownKeys).
5. Crea el recurso del paquete de Android: Llama a POST /v1/developerAccounts/{id}/androidPackages?androidPackageId={pkg} (CreateAndroidPackage) con el cuerpo {"name": ""} (crea el recurso en el estado DRAFT).
6. Registra la huella digital de la clave de firma de la app: Llama a POST /v1/developerAccounts/{id}/androidPackages/{pkg}/keys (CreateAndroidPackageKey) con el cuerpo JSON {"certificateFingerprintSha256": "..."}. Inspecciona el estado que se muestra:
   • DRAFT: Se requiere un comprobante de propiedad de la clave privada, y la respuesta incluye un verificationToken único para el paso 7.
   • IN_REVIEW: La prueba de propiedad y la justificación se omiten automáticamente (por ejemplo, cuando se registra un nombre de paquete nuevo que nunca se vio en Android o cuando ya verificaste la propiedad de esta clave de firma para otro nombre de paquete en el mismo DeveloperAccount). Omite el paso 7 y la llamada de justificación en el paso 8, y continúa directamente con el sondeo de GetAndroidPackage y GetAndroidPackageKey.
7. Compila y sube el APK de verificación (si el estado es DRAFT): Incorpora la cadena verificationToken que se muestra en assets/adi-registration.properties dentro de un APK mínimo que coincida con packageName, fírmalo con tu clave de firma de la app privada y súbelo con POST /upload/v1/developerAccounts/{id}/androidPackages/{pkg}/keys/{sha256}:verify (VerifyAndroidPackageKeyOwnership).
8. Envía la justificación (si es necesario) y sondea el estado del registro: Si la clave está en el estado OWNERSHIP_VERIFIED y registrationJustificationRequired es true, llama a POST /v1/developerAccounts/{id}/androidPackages/{pkg}/keys/{sha256}:justifyAndroidPackageKeyRegistration (JustifyAndroidPackageKeyRegistration). Sondea GetAndroidPackage y GetAndroidPackageKey hasta que state alcance REGISTERED.

Comandos de la CLI local para preparar huellas digitales de claves y APKs de verificación

• Extrae la huella digital del certificado SHA-256 de un almacén de claves (keytool):

  keytool -list -v -keystore release-key.jks -alias my-key-alias

• Verifica el resumen del certificado de firma SHA-256 en un APK compilado (apksigner):

  apksigner verify --print-certs app-release.apk

• Inspecciona el nombre del paquete del APK y el archivo de token incorporado antes de subirlo (aapt2 y unzip):

  aapt2 dump badging app-release.apk | head -n 1
  unzip -p app-release.apk assets/adi-registration.properties

Funciones de la IU y la API de Android Developer Console

Configuración y autenticación del servicio

Todas las solicitudes a la API deben usar HTTPS y, además, incluir un encabezado Authorization: Bearer ACCESS_TOKEN obtenido con el flujo del servidor web de OAuth 2.0 para una Cuenta de Google que haya completado la verificación de identidad del desarrollador en Android Developer Console.

Recursos y extremos de la API

La API de Android Developer Console organiza los recursos en la siguiente jerarquía:

• DeveloperAccount (developerAccounts/{developer_account})
  • AndroidPackage (developerAccounts/{developer_account}/androidPackages/{android_package})
    • AndroidPackageRegistrationPolicy (developerAccounts/{developer_account}/androidPackages/{android_package}/registrationPolicy)
    • AndroidPackageKey (developerAccounts/{developer_account}/androidPackages/{android_package}/keys/{key})

Recurso: DeveloperAccount

Representa una cuenta en Android Developer Console asociada con una identidad de desarrollador.

Enum: DeveloperAccount.VerificationState

Métodos: DeveloperAccount

Recurso: AndroidPackage

Representa un nombre de paquete de Android registrado o que se está registrando en un DeveloperAccount.

Enum: AndroidPackage.State

Recurso: AndroidPackageRegistrationPolicy

Es el recurso singleton que muestra GetAndroidPackageRegistrationPolicy y que describe las claves de firma públicas históricas detectadas para un nombre de paquete y si registrar el nombre del paquete con una clave de firma determinada requiere una justificación por escrito.

Enum: KnownKey.JustificationRequirement

Enum: AndroidPackageRegistrationPolicy.KeySelectionStrategy

Métodos: AndroidPackage

Recurso: AndroidPackageKey

Representa una huella digital del certificado de firma de apps pública asociada con un AndroidPackage y hace un seguimiento de la verificación de propiedad y el estado de revisión del registro.

Enum: AndroidPackageKey.State

Métodos: AndroidPackageKey

Manejo de errores

Cuando falla una solicitud a la API, la API de Android Developer Console devuelve un código de estado HTTP 4xx o 5xx y un cuerpo de error JSON google.rpc.Status estándar:

{
  "error": {
    "code": 400,
    "message": "Invalid certificate fingerprint SHA256 format.",
    "status": "INVALID_ARGUMENT",
    "details": []
  }
}

Códigos de estado HTTP y resoluciones comunes

Ejemplos de solicitudes y respuestas HTTP

Reemplaza los valores de marcador de posición, como ACCESS_TOKEN, 1234567890, com.example.myapp y 60e860e8..., por tus propios valores.

1. GetDeveloperAccount

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890"

Respuesta:

{
  "name": "developerAccounts/1234567890",
  "displayName": "Example Developer",
  "verificationState": "VERIFIED"
}

2. ListDeveloperAccounts

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts"

Respuesta:

{
  "developerAccounts": [
    {
      "name": "developerAccounts/1234567890",
      "displayName": "Example Developer",
      "verificationState": "VERIFIED"
    }
  ]
}

3. GetAndroidPackageRegistrationPolicy

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/registrationPolicy"

Respuesta:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/registrationPolicy",
  "knownKeys": [
    {
      "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
      "justificationRequirement": "NOT_REQUIRED"
    }
  ],
  "keySelectionStrategy": "SELECT_KEY_FROM_LIST"
}

4. CreateAndroidPackage

curl -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"name": ""}' \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages?androidPackageId=com.example.myapp"

Respuesta:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp",
  "packageName": "com.example.myapp",
  "state": "DRAFT",
  "registeredAppStore": false
}

5. GetAndroidPackage

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp"

Respuesta:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp",
  "packageName": "com.example.myapp",
  "state": "REGISTERED",
  "registeredAppStore": false
}

6. ListAndroidPackages

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages?pageSize=100"

Respuesta:

{
  "androidPackages": [
    {
      "name": "developerAccounts/1234567890/androidPackages/com.example.myapp",
      "packageName": "com.example.myapp",
      "state": "REGISTERED",
      "registeredAppStore": false
    }
  ],
  "nextPageToken": ""
}

7. CreateAndroidPackageKey

curl -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123"
  }' \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys"

Respuesta:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "state": "DRAFT",
  "verificationToken": "token_xyz987654321"
}

8. GetAndroidPackageKey

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123"

Respuesta:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "state": "REGISTERED"
}

9. ListAndroidPackageKeys

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys?pageSize=100"

Respuesta:

{
  "androidPackageKeys": [
    {
      "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
      "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
      "state": "REGISTERED"
    }
  ],
  "nextPageToken": ""
}

10. VerifyAndroidPackageKeyOwnership

Opción A: Carga de contenido multimedia de una sola solicitud

curl -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @app-release.apk \
  "https://androiddeveloperconsole.googleapis.com/upload/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123:verify?uploadType=media"

Opción B: Protocolo de carga reanudable (recomendado para APKs grandes o CI/CD)

Paso 1: Inicia la sesión de carga reanudable y extrae el encabezado X-Goog-Upload-URL que se muestra:

curl -i -X POST \
  "https://androiddeveloperconsole.googleapis.com/upload/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123:verify" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: FILE_SIZE_IN_BYTES" \
  -H "X-Goog-Upload-Header-Content-Type: application/vnd.android.package-archive" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123"
  }'

Paso 2: Sube el objeto binario del APK firmado a UPLOAD_SESSION_URI y finaliza la sesión:

curl -X PUT \
  "UPLOAD_SESSION_URI" \
  -H "Content-Length: FILE_SIZE_IN_BYTES" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@app-release.apk"

Respuesta:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "state": "IN_REVIEW"
}

11. JustifyAndroidPackageKeyRegistration

curl -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "justification": "We previously distributed com.example.myapp directly from https://downloads.example.com and are migrating to our rotated production key."
  }' \
  "https://androiddeveloperconsole.googleapis.com/v1/developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123:justifyAndroidPackageKeyRegistration"

Respuesta:

{
  "name": "developerAccounts/1234567890/androidPackages/com.example.myapp/keys/60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "certificateFingerprintSha256": "60e860e8d77251234567890abcdef1234567890abcdef1234567890abcdef123",
  "state": "IN_REVIEW",
  "registrationJustificationRequired": true
}

Recursos adicionales

• Cómo registrar nombres de paquetes con la API de Android Developer Console
• Verifica el estado de registro de la app con la API de Android Developer ID Status
• Cómo registrarse en Android Developer Console
• Regístrate en Google Play Console