Administra las aprobaciones

En este documento, se explica cómo administrar las aprobaciones en la API de Google Drive.

Los usuarios pueden enviar documentos en Google Drive a través de un proceso formal de aprobación. Puedes usar este proceso para obtener la aprobación de una revisión de contrato o un documento oficial antes de su publicación. Una aprobación hace un seguimiento del estado de la revisión (como En curso, Aprobada o Rechazada) y de los revisores involucrados. Las aprobaciones son una excelente manera de validar el contenido y mantener un registro de los revisores.

Puedes crear y administrar aprobaciones de contenido en Drive. La API de Google Drive proporciona el recurso approvals para trabajar con aprobaciones de archivos. Los métodos del recurso approvals funcionan en elementos de Drive, Documentos de Google y otros editores de Google Workspace. Los revisores pueden aprobar documentos, rechazarlos o dejar comentarios en ellos directamente.

Antes de comenzar

  1. Tu archivo debe contener la capacidad canStartApproval . Para verificar las capacidades de un archivo, llama al método get en el recurso files con el parámetro de ruta de acceso fileId y usa el campo de capacidad canStartApproval en el parámetro fields. Para obtener más información, consulta Información sobre las capacidades de los archivos.

    La capacidad booleana canStartApproval es false en los siguientes casos:

    • La configuración del administrador restringe el acceso a la función.
    • Tu edición de Google Workspace no es apta.
    • El archivo pertenece a un usuario ajeno a tu dominio.
    • El usuario no tiene el permiso role=writer en el archivo.

  2. Asegúrate de compartir manualmente el archivo de destino con los revisores. Drive no lo hace automáticamente. Si un revisor no tiene acceso al archivo, la solicitud de aprobación se realizará correctamente, pero no recibirá notificaciones ni podrá ver el archivo.

Conceptos

Los siguientes conceptos clave forman la base de las aprobaciones.

Estado de aprobación

Cuando solicitas la aprobación de un documento, el proceso de aprobación garantiza que cada revisor apruebe la misma versión del contenido. Si se edita el archivo después de que un revisor aprueba la solicitud y antes de que se complete, se restablecerán las aprobaciones del revisor y los revisores deberán aprobar la nueva versión. Si se edita el contenido después de la aprobación final, aparecerá un banner en el documento que indicará que la versión actual difiere de la aprobada.

El recurso approvals incluye un objeto Status que detalla el estado de la aprobación cuando se solicita el recurso. También incluye el objeto ReviewerResponse, que detalla las respuestas a una aprobación realizada por revisores específicos. La respuesta de cada revisor se representa con el objeto Response.

Cada acción del proceso de aprobación genera notificaciones por correo electrónico que se envían al iniciador (el usuario que solicita la aprobación) y a todos los revisores. También se agrega al registro de actividad de aprobaciones.

Todos los revisores deben aprobar una aprobación. Cualquier revisor que rechace una aprobación establece el estado completado en DECLINED.

Una vez que se completa una aprobación (el estado es APPROVED, CANCELLED o DECLINED), permanece en el estado completado y el iniciador o los revisores no pueden interactuar con ella. Puedes agregar comentarios a una aprobación completada siempre y cuando no haya una aprobación existente en un archivo con el estado IN_PROGRESS.

Ciclo de vida de una aprobación

Es el ciclo de vida de una aprobación.
Figura 1: Es el ciclo de vida de una aprobación.

Una aprobación pasa por varios estados durante su ciclo de vida. En la figura 1, se muestran los pasos generales del ciclo de vida de una aprobación:

  1. Inicia la aprobación. Llama a start para comenzar la solicitud de aprobación. Luego, status se configura como IN_PROGRESS.

  2. La aprobación está pendiente. Mientras la aprobación está pendiente (status se establece en IN_PROGRESS), tanto el iniciador como los revisores pueden interactuar con ella. Pueden agregar un comment, el iniciador puede reassign revisores y uno o más revisores pueden approve la solicitud.

  3. La aprobación está en el estado completado. Una aprobación entra en el estado de completada (status se establece en APPROVED, CANCELLED o DECLINED) cuando todos los revisores aprueban la solicitud, el iniciador elige cancel la solicitud o si algún revisor elige decline la solicitud.

Usa el parámetro fields

Si deseas especificar los campos que se devolverán en la respuesta, puedes establecer el parámetro del sistema fields con cualquier método del recurso approvals. Si omites el parámetro fields, el servidor devolverá un conjunto predeterminado de campos específicos para el método. Para devolver diferentes campos, consulta Cómo devolver campos específicos.

Cómo iniciar y administrar aprobaciones

El recurso approvals se puede usar para iniciar y administrar aprobaciones con la API de Drive. Estos métodos funcionan con cualquiera de los alcances existentes de la API de Drive de OAuth 2.0 que permiten escribir metadatos de archivos. Para obtener más información, consulta Cómo elegir los permisos de la API de Google Drive.

Iniciar aprobación

Para iniciar una nueva aprobación en un archivo, usa el método start en el recurso approvals y, luego, incluye el parámetro de ruta de acceso fileId.

El cuerpo de la solicitud consta de un campo reviewerEmails obligatorio que es un array de cadenas que contiene las direcciones de correo electrónico de los revisores asignados para revisar el archivo. Cada dirección de correo electrónico del revisor debe estar asociada a una Cuenta de Google, o la solicitud fallará. Además, se ofrecen tres campos opcionales:

  • dueTime: Es la fecha límite para la aprobación en formato RFC 3339.
  • lockFile: Es un valor booleano que indica si se debe bloquear el archivo cuando se inicia la aprobación. Esto impide que los usuarios modifiquen el archivo durante el proceso de aprobación. Cualquier usuario con el permiso role=writer puede quitar este bloqueo.
  • message: Es un mensaje personalizado que se envía a los revisores.

El cuerpo de la respuesta contiene una instancia del recurso approvals y el campo initiator, que es el usuario que solicitó la aprobación. La aprobación Status se establece en IN_PROGRESS.

Si hay una aprobación existente con un Status de IN_PROGRESS, el método start falla. Solo puedes iniciar una aprobación si no hay una aprobación existente en el archivo o si la aprobación existente está en estado completado (el estado es APPROVED, CANCELLED o 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."
 }'

Reemplaza lo siguiente:

  • FILE_ID: Es el ID del archivo en el que se encuentra la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Comentario sobre la aprobación

Para comentar una aprobación, usa el método comment en el recurso approvals y, luego, incluye los parámetros de ruta de acceso fileId y approvalId.

El cuerpo de la solicitud consta de un campo message obligatorio que es una cadena que contiene el comentario que deseas agregar a la aprobación.

El cuerpo de la respuesta contiene una instancia del recurso approvals. El mensaje se envía a los iniciadores y revisores de la aprobación como una notificación, y también se incluye en el registro de actividad de aprobación.

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."
 }'

Reemplaza lo siguiente:

  • FILE_ID: Es el ID del archivo en el que se encuentra la aprobación.
  • APPROVAL_ID: ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Cómo reasignar revisores en la aprobación

Para reasignar revisores en una aprobación, usa el método reassign en el recurso approvals y, luego, incluye los parámetros de ruta de acceso fileId y approvalId.

El método reassign permite que el iniciador de la aprobación (o un usuario con el permiso role=writer) agregue o reemplace revisores en el objeto ReviewerResponse del recurso approvals. Un usuario con el permiso role=reader solo puede reasignar una aprobación que se le haya asignado a él. Esto permite que el usuario reasigne una solicitud a otra persona que sea un revisor más capaz.

Los revisores solo se pueden reasignar mientras el campo Status es IN_PROGRESS y el campo response del revisor que se reasigna está establecido en NO_RESPONSE.

Ten en cuenta que no puedes quitar a un revisor de una aprobación. Si necesitas quitar a un revisor, debes cancelar la aprobación y comenzar una nueva.

El cuerpo de la solicitud consta de los campos opcionales addReviewers y replaceReviewers. Cada campo tiene un objeto repetido para AddReviewer y ReplaceReviewer, que contienen un solo revisor para agregar o un par de revisores para reemplazar. También puedes agregar el campo opcional message que contiene el comentario que deseas enviar a los revisores nuevos.

El cuerpo de la respuesta contiene una instancia del recurso approvals. El mensaje se envía a los revisores nuevos como una notificación y también se incluye en el registro de actividad de aprobación.

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."
 }'

Reemplaza lo siguiente:

  • FILE_ID: Es el ID del archivo en el que se encuentra la aprobación.
  • APPROVAL_ID: ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Cancelar la aprobación

Para cancelar una aprobación, usa el método cancel en el recurso approvals y, luego, incluye los parámetros de ruta fileId y approvalId.

El método cancel solo puede ser llamado por el iniciador de la aprobación (o un usuario con el permiso role=writer) mientras la aprobación Status está en IN_PROGRESS.

El cuerpo de la solicitud consta de un campo message opcional que es una cadena que contiene el mensaje para acompañar la cancelación de la aprobación.

El cuerpo de la respuesta contiene una instancia del recurso approvals. El mensaje se envía como una notificación y también se incluye en el registro de actividad de aprobación. La aprobación Status se establece en CANCELLED y se encuentra en estado completado.

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."
 }'

Reemplaza lo siguiente:

  • FILE_ID: Es el ID del archivo en el que se encuentra la aprobación.
  • APPROVAL_ID: ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Rechazar la aprobación

Para rechazar una aprobación, usa el método decline en el recurso approvals y, luego, incluye los parámetros de ruta de acceso fileId y approvalId.

Solo se puede llamar al método decline mientras la aprobación Status sea IN_PROGRESS.

El cuerpo de la solicitud consta de un campo message opcional que es una cadena que contiene el mensaje para acompañar el rechazo de la aprobación.

El cuerpo de la respuesta contiene una instancia del recurso approvals. El mensaje se envía como una notificación y también se incluye en el registro de actividad de aprobación. El campo response del objeto ReviewerResponse del usuario solicitante se establece en DECLINED. Además, la aprobación Status se establece en DECLINED y se encuentra en un estado completado.

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."
 }'

Reemplaza lo siguiente:

  • FILE_ID: Es el ID del archivo en el que se encuentra la aprobación.
  • APPROVAL_ID: ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Aprobar la aprobación

Para aprobar una aprobación, usa el método approve en el recurso approvals y, luego, incluye los parámetros de ruta de acceso fileId y approvalId.

Solo se puede llamar al método approve mientras la aprobación Status sea IN_PROGRESS.

El cuerpo de la solicitud consta de un campo message opcional que es una cadena que contiene el mensaje para acompañar la aprobación.

El cuerpo de la respuesta contiene una instancia del recurso approvals. El mensaje se envía como una notificación y también se incluye en el registro de actividad de aprobación. El campo response del objeto ReviewerResponse del usuario solicitante se establece en APPROVED. Además, si esta es la última respuesta obligatoria del revisor, la aprobación Status se establece en APPROVED y se encuentra en un estado completado.

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."
 }'

Reemplaza lo siguiente:

  • FILE_ID: Es el ID del archivo en el que se encuentra la aprobación.
  • APPROVAL_ID: ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Cómo encontrar aprobaciones existentes

El recurso approvals también se puede usar para obtener y enumerar el estado de tus aprobaciones con la API de Drive.

Para ver las aprobaciones de un archivo, debes tener permiso para leer sus metadatos. Para obtener más información, consulta Roles y permisos.

Obtén la aprobación

Para obtener la aprobación de un archivo, usa el método get en el recurso approvals con los parámetros de ruta de acceso fileId y approvalId. Si no conoces el ID de aprobación, puedes listar las aprobaciones con el método list.

El cuerpo de la respuesta contiene una instancia del 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'

Reemplaza lo siguiente:

  • FILE_ID: Es el ID del archivo en el que se encuentra la aprobación.
  • APPROVAL_ID: ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Enumera las aprobaciones

Para enumerar las aprobaciones de un archivo, llama al método list en el recurso approvals y, luego, incluye el parámetro de ruta de acceso fileId.

El cuerpo de la respuesta consta de una lista de aprobaciones en el archivo. El campo items incluye información sobre cada aprobación en forma de un recurso approvals.

También puedes pasar los siguientes parámetros de consulta para personalizar la paginación o filtrar las aprobaciones:

  • pageSize: Es la cantidad máxima de aprobaciones que se mostrarán por página. Si no configuras pageSize, el servidor devuelve hasta 100 aprobaciones.

  • pageToken: Es un token de página que se recibió de una llamada a lista anterior. Este token se usa para recuperar la página siguiente. Se debe establecer en el valor de nextPageToken de una respuesta 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'

Reemplaza lo siguiente:

  • FILE_ID: Es el ID del archivo en el que se encuentra la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.