Gerenciar aprovações

Este documento explica como gerenciar aprovações na API Google Drive.

Os usuários podem enviar documentos no Google Drive por um processo de aprovação formal. Você pode usar esse processo para receber aprovações de uma revisão de contrato ou de um documento oficial antes da publicação. Uma aprovação acompanha o status da revisão (como "Em andamento", "Aprovada" ou "Recusada") e dos revisores envolvidos. As aprovações são uma excelente maneira de validar o conteúdo e manter um registro dos revisores.

Você pode criar e gerenciar aprovações de conteúdo no Drive. A API Google Drive oferece o recurso approvals para trabalhar com aprovações de arquivos. Os métodos do recurso approvals funcionam em itens do Drive, do Google Docs e de outros editores do Google Workspace. Os revisores podem aprovar, rejeitar ou dar feedback diretamente nos documentos.

Antes de começar

O arquivo precisa conter o recurso canStartApproval . Para verificar as funcionalidades do arquivo, chame o método get no recurso files com o parâmetro de caminho fileId e use o campo de funcionalidade canStartApproval no parâmetro fields. Para mais informações, consulte Entender os recursos de arquivos.

A capacidade booleana canStartApproval é false quando:
- As configurações de administrador restringem o acesso ao recurso.
- Sua edição do Google Workspace não está qualificada.
- O arquivo pertence a um usuário fora do seu domínio.
- O usuário não tem a permissão role=writer no arquivo.
Compartilhe manualmente o arquivo de destino com os revisores. O Drive não faz isso automaticamente. Se um revisor não tiver acesso ao arquivo, o pedido de aprovação será aceito, mas ele não vai receber notificações nem poderá ver o arquivo.

Conceitos

Os seguintes conceitos principais formam a base das aprovações.

Status da aprovação

Quando você pede a aprovação de um documento, o processo garante que todos os revisores aprovem a mesma versão do conteúdo. Se o arquivo for editado depois que um revisor aprovar o pedido e antes da conclusão, as aprovações do revisor serão redefinidas, e ele precisará aprovar a nova versão. Se o conteúdo for editado após a aprovação final, um banner vai aparecer no documento indicando que a versão atual é diferente da aprovada.

O recurso approvals inclui um objeto Status que detalha o status da aprovação quando o recurso é solicitado. Ele também inclui o objeto ReviewerResponse, que detalha as respostas a uma aprovação feita por revisores específicos. A resposta de cada revisor é representada pelo objeto Response.

Cada ação no processo de aprovação gera notificações por e-mail que são enviadas ao iniciador (o usuário que solicita a aprovação) e a todos os revisores. Ele também é adicionado ao registro de atividades de aprovação.

Todos os revisores precisam aprovar uma aprovação. Qualquer revisor que recusar uma aprovação define o estado concluído como DECLINED.

Depois que uma aprovação é concluída (o status é APPROVED, CANCELLED ou DECLINED), ela permanece no estado concluído e não pode ser acessada pelo iniciador ou pelos revisores. Você pode adicionar comentários a uma aprovação concluída, desde que não haja uma aprovação em um arquivo com o status IN_PROGRESS.

Ciclo de vida de uma aprovação

Uma aprovação passa por vários estados durante o ciclo de vida. A Figura 1 mostra as etapas de alto nível de um ciclo de vida de aprovação:

Iniciar a aprovação. Chame start para iniciar o pedido de aprovação. O status é definido como IN_PROGRESS.
A aprovação está pendente. Enquanto a aprovação está pendente (status está definido como IN_PROGRESS), o iniciador e os revisores podem interagir com ela. Eles podem adicionar um comment, o iniciador pode reassign revisores, e um ou mais revisores podem approve o pedido.
A aprovação está no estado concluído. Uma aprovação entra no estado concluído (status é definido como APPROVED, CANCELLED ou DECLINED) quando todos os revisores aprovam a solicitação, o iniciador escolhe cancel a solicitação ou se qualquer revisor escolhe decline a solicitação.

Usar o parâmetro "fields"

Se você quiser especificar os campos a serem retornados na resposta, defina o parâmetro do sistema fields com qualquer método do recurso approvals. Se você omitir o parâmetro fields, o servidor vai retornar um conjunto padrão de campos específicos do método. Para retornar campos diferentes, consulte Retornar campos específicos.

Iniciar e administrar aprovações

O recurso approvals pode ser usado para iniciar e gerenciar aprovações usando a API Drive. Esses métodos funcionam com qualquer um dos escopos da API Drive OAuth 2.0 que permitem gravar metadados de arquivos. Para mais informações, consulte Escolher escopos da API Google Drive.

Iniciar aprovação

Para iniciar uma nova aprovação em um arquivo, use o método start no recurso approvals e inclua o parâmetro de caminho fileId.

O corpo da solicitação consiste em um campo reviewerEmails obrigatório, que é uma matriz de strings contendo os endereços de e-mail dos revisores atribuídos para analisar o arquivo. Cada endereço de e-mail do revisor precisa estar associado a uma Conta do Google, caso contrário, a solicitação vai falhar. Além disso, três campos opcionais são oferecidos:

dueTime: o prazo para aprovação no formato RFC 3339.
lockFile: um booleano que indica se o arquivo será bloqueado ao iniciar a aprovação. Isso impede que os usuários modifiquem o arquivo durante o processo de aprovação. Qualquer usuário com a permissão role=writer pode remover esse bloqueio.
message: uma mensagem personalizada enviada aos revisores.

O corpo da resposta contém uma instância do recurso approvals e inclui o campo initiator, que é o usuário que solicitou a aprovação. A aprovação Status está definida como IN_PROGRESS.

Se houver uma aprovação com um Status de IN_PROGRESS, o método start vai falhar. Só é possível iniciar uma aprovação se não houver uma aprovação no arquivo ou se a aprovação estiver no estado concluído (o status é APPROVED, CANCELLED ou DECLINED).

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals:start' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "reviewerEmails": [
     "reviewer1@example.com",
     "reviewer2@example.com"
    ],
    "dueTime": "2026-04-01T15:01:23Z",
    "lockFile": true,
    "message": "Please review this file for approval."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
ACCESS_TOKEN: o token OAuth 2.0 do app.

Comentar na aprovação

Para comentar uma aprovação, use o método comment no recurso approvals e inclua os parâmetros de caminho fileId e approvalId.

O corpo da solicitação consiste em um campo message obrigatório, que é uma string contendo o comentário que você quer adicionar à aprovação.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada ao iniciador e aos revisores da aprovação como uma notificação e também é incluída no registro de atividades de aprovação.

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:comment' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The required comment on the approval."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do app.

Reatribuir revisores na aprovação

Para reatribuir revisores em uma aprovação, use o método reassign no recurso approvals e inclua os parâmetros de caminho fileId e approvalId.

O método reassign permite que o iniciador da aprovação (ou um usuário com a permissão role=writer) adicione ou substitua revisores no objeto ReviewerResponse do recurso approvals. Um usuário com a permissão role=reader só pode reatribuir uma aprovação que foi atribuída a ele mesmo. Isso permite que o usuário reatribua uma solicitação a outra pessoa que seja um revisor mais capaz.

Os revisores só podem ser reatribuídos enquanto o Status estiver IN_PROGRESS e o campo response do revisor que está sendo reatribuído estiver definido como NO_RESPONSE.

Não é possível remover um revisor de uma aprovação. Se você precisar remover um revisor, cancele a aprovação e comece uma nova.

O corpo da solicitação consiste nos campos opcionais addReviewers e replaceReviewers. Cada campo tem um objeto repetido para AddReviewer e ReplaceReviewer, que contêm um único revisor para adicionar ou um par de revisores para substituir. Você também pode adicionar o campo opcional message com o comentário que quer enviar aos novos revisores.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada aos novos revisores como uma notificação e também é incluída no registro de atividades de aprovação.

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:reassign' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "addReviewers": [
    {
        "addedReviewerEmail": "new_reviewer@example.com"
    }
    ],
    "replaceReviewers": [
    {
        "addedReviewerEmail": "replacement_reviewer@example.com",
        "removedReviewerEmail": "old_reviewer@example.com"
    }
    ],
    "message": "Reassigning reviewers for this approval request."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do app.

Cancelar aprovação

Para cancelar uma aprovação, use o método cancel no recurso approvals e inclua os parâmetros de caminho fileId e approvalId.

O método cancel só pode ser chamado pelo iniciador da aprovação (ou um usuário com a permissão role=writer) enquanto o Status de aprovação estiver IN_PROGRESS.

O corpo da solicitação consiste em um campo message opcional, que é uma string contendo a mensagem para acompanhar o cancelamento da aprovação.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada como uma notificação e também incluída no registro de atividades de aprovação. A aprovação Status é definida como CANCELLED e está em um estado concluído.

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:cancel' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for cancelling this approval request."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do app.

Recusar aprovação

Para recusar uma aprovação, use o método decline no recurso approvals e inclua os parâmetros de caminho fileId e approvalId.

O método decline só pode ser chamado enquanto o Status de aprovação for IN_PROGRESS.

O corpo da solicitação consiste em um campo message opcional, que é uma string contendo a mensagem que acompanha a recusa da aprovação.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada como uma notificação e também incluída no registro de atividades de aprovação. O campo response do objeto ReviewerResponse do usuário solicitante está definido como DECLINED. Além disso, a aprovação Status é definida como DECLINED e está em um estado concluído.

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:decline' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for declining this approval request."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do app.

Aprovar a aprovação

Para aprovar uma aprovação, use o método approve no recurso approvals e inclua os parâmetros de caminho fileId e approvalId.

O método approve só pode ser chamado enquanto o Status de aprovação for IN_PROGRESS.

O corpo da solicitação consiste em um campo message opcional, que é uma string contendo a mensagem para acompanhar a aprovação.

O corpo da resposta contém uma instância do recurso approvals. A mensagem é enviada como uma notificação e também incluída no registro de atividades de aprovação. O campo response do objeto ReviewerResponse do usuário solicitante está definido como APPROVED. Além disso, se esta for a última resposta necessária do revisor, a aprovação Status será definida como APPROVED e estará no estado concluído.

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:approve' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for approving this approval request."
 }'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do app.

Localizar aprovações

O recurso approvals também pode ser usado para receber e listar o status das suas aprovações usando a API Drive.

Para ver as aprovações em um arquivo, é necessário ter permissão para ler os metadados dele. Para mais informações, consulte Papéis e permissões.

Receber aprovação

Para receber uma aprovação em um arquivo, use o método get no recurso approvals com os parâmetros de caminho fileId e approvalId. Se você não souber o ID da aprovação, poderá listar aprovações usando o método list.

O corpo da resposta contém uma instância do recurso approvals.

cURL

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
APPROVAL_ID: o ID da aprovação.
ACCESS_TOKEN: o token OAuth 2.0 do app.

Listar aprovações

Para listar as aprovações em um arquivo, chame o método list no recurso approvals e inclua o parâmetro de caminho fileId.

O corpo da resposta consiste em uma lista de aprovações no arquivo. O campo items inclui informações sobre cada aprovação na forma de um recurso approvals.

Também é possível transmitir os seguintes parâmetros de consulta para personalizar a paginação ou filtrar as aprovações:

pageSize: o número máximo de aprovações a serem retornadas por página. Se você não definir pageSize, o servidor vai retornar até 100 aprovações.
pageToken: um token de página recebido de uma chamada de lista anterior. Esse token é usado para recuperar a página seguinte. Ele precisa ser definido como o valor de nextPageToken de uma resposta anterior.

cURL

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Substitua:

FILE_ID: o ID do arquivo em que a aprovação está.
ACCESS_TOKEN: o token OAuth 2.0 do app.

Gerenciar aprovações Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Conceitos

Status da aprovação

Ciclo de vida de uma aprovação

Usar o parâmetro "fields"

Iniciar e administrar aprovações

Iniciar aprovação

cURL

Comentar na aprovação

cURL

Reatribuir revisores na aprovação

cURL

Cancelar aprovação

cURL

Recusar aprovação

cURL

Aprovar a aprovação

cURL

Localizar aprovações

Receber aprovação

cURL

Listar aprovações

cURL

Temas relacionados

Gerenciar aprovações