Verificar o status do registro do app com a API Android Developer ID Status

Use a API Android Developer Status para verificar se um nome de pacote de app Android está registrado em nome de um desenvolvedor verificado. Se você cria ferramentas de desenvolvimento de software, IDEs ou fluxos de trabalho automatizados de CI/CD, pode integrar essa API de servidor para servidor para fazer o seguinte:

• Verificar se um nome de pacote do app está registrado em nome de um desenvolvedor verificado
• Validar se a impressão digital SHA-256 do certificado de assinatura de um app corresponde às credenciais registradas para o nome do pacote
• Solicitar que os desenvolvedores na interface da sua ferramenta registrem apps não reconhecidos no programa de verificação de desenvolvedor Android

Essa API foi projetada para oferecer suporte a vários fluxos de trabalho de desenvolvedores:

Este guia explica como concluir as seguintes tarefas:

1. Configurar o acesso e a autenticação da API Google Cloud.
2. Verificar se um nome de pacote e um par de impressão digital SHA-256 de certificado público de um app foram registrados no programa de verificação de desenvolvedor Android por um desenvolvedor verificado, com a impressão digital SHA-256 do certificado público fornecida ou uma impressão digital SHA-256 de certificado público diferente.
3. Processar estados de registro de API no fluxo de trabalho da sua ferramenta de desenvolvimento ou IDE.

Pré-requisitos

Este documento é destinado a desenvolvedores de apps Android ou de ferramentas de desenvolvimento de software. Antes de começar, você precisa ter:

• Acesso administrativo a um projeto do Google Cloud.
• Um conhecimento básico de APIs RESTful, JSON e impressões digitais de certificado SHA-256.

Você também precisa conhecer estes termos:

Endpoint de serviço

Um endpoint de serviço é um URL de base que especifica o endereço de rede de um serviço de API. Esse serviço tem o endpoint a seguir e todos os URIs são relativos a ele:

https://androiddeveloperidstatus.googleapis.com

Ativar a API

Para usar a API Android Developer ID Status, conclua as etapas de configuração para criar um projeto e ativar a API.

Criar um projeto do Google Cloud

1. Crie uma conta do Google Cloud se você não tiver uma.
2. Abra o Console do Google Cloud.
3. Crie um projeto do Google Cloud.

Ativar a API no seu projeto

1. No Console do Google Cloud, acesse APIs e serviços > Biblioteca.
2. Selecione seu projeto no menu suspenso.
3. Pesquise API Android Developer ID Status.
4. Clique em Ativar.

Autenticar

A API oferece suporte a credenciais de chave de API. Para gerar uma chave de API:

1. No console do Google Cloud, acesse APIs e serviços > Credenciais.
2. Clique em + Criar credenciais e selecione Chave de API.
3. Configure a chave e copie-a. Use essa chave nos cabeçalhos de solicitação.

Verificar o status de registro do app

Você pode consultar o recurso PackageRegistrationStatus para verificar um nome de pacote sozinho ou verificar um nome de pacote pareado com uma impressão digital do certificado específica.

Verificar um nome de pacote

Para verificar se um nome de pacote de app está registrado por um desenvolvedor verificado, faça uma solicitação GET autenticada que contenha o nome do pacote do app Android (por exemplo, com.example.app) para o endpoint packageRegistrationStatus:check sem parâmetros opcionais:

Solicitação:

curl -X GET "https://androiddeveloperidstatus.googleapis.com/v1/packages/com.example.app/packageRegistrationStatus:check" \
  -H "X-Goog-Api-Key: [key]"

Resultados

Resposta (registrada):

Se o nome do pacote estiver registrado, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "REGISTERED"
}

Ação recomendada: informe ao desenvolvedor que o nome do pacote já está registrado.

Resposta (não registrada):

Se o nome do pacote não estiver registrado, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "NOT_REGISTERED"
}

Verificar pares de nome de pacote e impressão digital do certificado

Para verificar se um pacote do app está registrado com uma impressão digital SHA-256 de certificado público específica, transmita o parâmetro de consulta certificateFingerprint:

Solicitação:

curl -X GET "https://androiddeveloperidstatus.googleapis.com/v1/packages/com.example.app/packageRegistrationStatus:check?certificateFingerprint=d6ac89ed1d0a805aad4b087d06d5f41645b814480b133fbc867ef7498d069e06" \
  -H "X-Goog-Api-Key: [key]"

Resultados

Resposta (registrada com impressão digital de certificado correspondente):

Se o nome do pacote estiver registrado com a impressão digital SHA-256 do certificado público fornecida, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "REGISTERED"
}

Resposta (registrada com impressão digital de certificado diferente):

Se o nome do pacote estiver registrado com uma impressão digital SHA-256 de certificado diferente da fornecida, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "REGISTERED_WITH_ANOTHER_CERTIFICATE_FINGERPRINT"
}

Resposta (não registrada):

Se o nome do pacote não estiver registrado com a impressão digital SHA-256 do certificado público fornecida, você vai receber o seguinte corpo de resposta HTTP com o código de resposta HTTP 200:

{
  "name": "packages/com.example.app/packageRegistrationStatus",
  "state": "NOT_REGISTERED"
}

Exemplo de implementação em Java

A classe Java a seguir demonstra como chamar a API usando o HttpClient padrão do Java 11.

import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class DeveloperIdStatusClient {

  private static final String API_ENDPOINT = "https://androiddeveloperidstatus.googleapis.com";

  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY";
    String packageName = "com.example.app";
    String certificateFingerprint = "d6ac89ed1d0a805aad4b087d06d5f41645b814480b133fbc867ef7498d069e06";

    try {
      String response = checkPackageRegistrationStatus(apiKey, packageName, certificateFingerprint);
      System.out.println("Response: " + response);
    } catch (IOException | InterruptedException e) {
      e.printStackTrace();
    }
  }

  /**
   *   Checks the registration status of an Android package.
   *
   *   @param apiKey The Google API key for authentication.
   *   @param packageName The fully-qualified Android package name (for example, "com.example.app").
   *   @param certificateFingerprint Optional SHA-256 certificate fingerprint. Pass null or empty to omit.
   *   @return The JSON response string from the API.
   */
  public static String checkPackageRegistrationStatus(
      String apiKey, String packageName, String certificateFingerprint)
      throws IOException, InterruptedException {

    // 1. Build the URL path (accepts dots directly)
    // Format: /v1/packages/{package}/packageRegistrationStatus:check
    String path = String.format("/v1/packages/%s/packageRegistrationStatus:check", packageName);

    // 2. Build query parameters (only certificateFingerprint if provided)
    StringBuilder queryBuilder = new StringBuilder();
    if (certificateFingerprint != null && !certificateFingerprint.isEmpty()) {
      queryBuilder.append("certificateFingerprint=")
          .append(URLEncoder.encode(certificateFingerprint, StandardCharsets.UTF_8));
    }

    String fullUrl = API_ENDPOINT + path;
    if (queryBuilder.length() > 0) {
      fullUrl += "?" + queryBuilder.toString();
    }

    // 3. Create and send the HTTP GET request with API Key header
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(fullUrl))
        .header("Accept", "application/json")
        .header("X-Goog-Api-Key", apiKey)
        .GET()
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    if (response.statusCode() != 200) {
      throw new IOException("Unexpected response code: " + response.statusCode() + ", body: " + response.body());
    }

    return response.body();
  }
}

Entender os estados de registro e o tratamento de erros

Quando uma solicitação de API falha, a API Android Developer ID Status retorna um objeto de erro JSON padrão do Google Cloud no corpo da resposta. Esse objeto fornece uma estrutura consistente para entender e processar o erro.

Exemplo de resposta de erro:

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }
}

O objeto de erro contém os seguintes campos de chave:

• code: o código de status HTTP (por exemplo, 400, 403, 500).
• message: uma descrição do erro em inglês para desenvolvedores. Essa mensagem não é estável e pode mudar. Portanto, não crie uma lógica de análise com base nela.
• status: um código de erro canônico que identifica programaticamente o tipo de erro (por exemplo, INVALID_ARGUMENT, PERMISSION_DENIED). A lógica de tratamento de erros precisa ser criada com base nesse identificador estável.

A tabela a seguir lista os erros mais comuns retornados pela API e o curso de ação recomendado.

Limites de cotas

As cotas de uso são aplicadas por projeto para garantir a confiabilidade do serviço.

Monitorar o uso

É possível monitorar o uso atual da API do seu projeto e verificar a proximidade dos limites de cota diretamente no console do Google Cloud.

1. Acesse a página APIs e serviços > Painel.
2. Selecione a API Android Developer ID Status.
3. Clique na guia Cotas.

Esse painel oferece uma análise detalhada do volume de solicitações ao longo do tempo.