Administra 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 mediante 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, Aprobado o Rechazado) 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 approvals recurso para trabajar con las aprobaciones de archivos. Los métodos del recurso approvals funcionan en elementos de Drive, Google Docs y otros editores de Google Workspace. Los revisores pueden aprobar el documento, rechazarlo o dejar comentarios en él directamente.

Antes de comenzar

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

    La capacidad booleana canStartApproval es false cuando sucede lo siguiente:

    • 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 que no pertenece 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 se asegura de que cada revisor pueda proporcionar información sobre el documento.

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

El comportamiento de la aprobación cuando se cambia el contenido del archivo mientras el Status es IN_PROGRESS está determinado por el fileContentChangeBehavior campo del approvals recurso. Se pueden aplicar los siguientes comportamientos:

  • RESET_APPROVAL: El proceso de aprobación se asegura de 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 restablecen las aprobaciones del revisor (la respuesta vuelve a NO_RESPONSE) y los revisores deben aprobar la nueva versión. Cuando la aprobación tiene un estado de APPROVED, el archivo se bloquea para evitar más modificaciones. Las ediciones de contenido adicionales después de la aprobación final harán que aparezca un banner en el documento que indica que la versión actual difiere de la aprobada. Este es el comportamiento predeterminado.

  • NO_APPROVAL_ACTION: Las ediciones del contenido del archivo no restablecen las decisiones del revisor mientras la aprobación está pendiente. Además, el archivo no se bloquea en la aprobación final. Los revisores también pueden restablecer su propia decisión APPROVED al estado pendiente (la respuesta vuelve a NO_RESPONSE) en cualquier momento antes de que se complete la aprobación.

Una vez que se completa la aprobación, este comportamiento ya no se aplica.

Cada acción en el 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 aprobación.

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 que no haya una aprobación existente en un archivo con un estado de IN_PROGRESS.

Ciclo de vida de una aprobación

Es el ciclo de vida de una aprobación.
Figura 1. 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 de alto nivel de un ciclo de vida de aprobación:

  1. Inicia la aprobación. Llama a start para iniciar la solicitud de aprobación. Luego, el status se establece en 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 ingresa al estado completado (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

Para recuperar los detalles de la aprobación, debes especificar explícitamente los campos que deseas usar el fields sistema parámetro con cualquier método del recurso approvals. A diferencia de otros recursos, los métodos del recurso approvals no muestran un conjunto predeterminado de campos cuando se omite el parámetro fields. Para obtener más información, consulta Cómo mostrar campos específicos.

Inicia y administra 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 permisos existentes de la API de Drive de OAuth 2.0 que permiten escribir metadatos de archivos. Para obtener más información, consulta Elige permisos de la API de Google Drive.

Iniciar aprobación

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

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 con una Cuenta de Google o la solicitud fallará. Además, se ofrecen cuatro campos opcionales:

  • dueTime: La fecha límite para la aprobación en formato RFC 3339.
  • lockFile: 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: Un mensaje personalizado que se envía a los revisores.
  • fileContentChangeBehavior: El comportamiento de la aprobación cuando cambia el contenido del archivo. Los valores admitidos son los siguientes:
    • RESET_APPROVAL: (Predeterminado) Restablece cualquier respuesta del revisor de APPROVED a NO_RESPONSE cuando cambia el contenido mientras la aprobación está en curso. El archivo se bloquea una vez que se completa la aprobación con un estado de APPROVED.
    • NO_APPROVAL_ACTION: No restablece las respuestas del revisor cuando cambia el contenido y no bloquea el archivo cuando se completa la aprobación.

El cuerpo de la respuesta contiene una instancia del recurso approvals y incluye el initiator campo que es el usuario que solicitó la aprobación. El Status de aprobación 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 el 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.",
    "fileContentChangeBehavior": "RESET_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.

Comentar sobre la aprobación

Para comentar sobre una aprobación, usa el comment método en el recurso approvals e 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 al iniciador y a los 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: Es el ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Reasignar revisores en la aprobación

Para reasignar revisores en una aprobación, usa el reassign método en el recurso approvals e 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 asigne. 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 Status es IN_PROGRESS y el response campo para el revisor que se reasigna se establece en NO_RESPONSE.

Ten en cuenta que no puedes quitar un revisor en una aprobación. Si necesitas quitar 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 message opcional 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: Es el ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Cancelar aprobación

Para cancelar una aprobación, usa el cancel método en el approvals recurso e incluye los parámetros de ruta de acceso 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 el Status de aprobación es 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. El Status de aprobación se establece en CANCELLED y está en un 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: Es el ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Rechazar aprobación

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

El método decline solo se puede llamar mientras el Status de aprobación es 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 response campo del ReviewerResponse objeto del usuario solicitante se establece en DECLINED. Además, el Status de aprobación se establece en DECLINED y está 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: Es el ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Aprobar aprobación

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

El método approve solo se puede llamar mientras el Status de aprobación es IN_PROGRESS.

El cuerpo de la solicitud consta de un campo opcional message 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 response campo del ReviewerResponse objeto del usuario solicitante se establece en APPROVED. Además, si esta es la última respuesta obligatoria del revisor, el Status de aprobación se establece en APPROVED y está 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: Es el ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Ubica las 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 en un archivo, debes tener permiso para leer los metadatos del archivo. Para obtener más información, consulta Funciones y permisos.

Obtener aprobación

Para obtener una aprobación en un archivo, usa el get método en el recurso approvals con los parámetros de ruta de acceso fileId y approvalId. Si no conoces el ID de aprobación, puedes enumerar 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: Es el ID de la aprobación.
  • ACCESS_TOKEN: Es el token de OAuth 2.0 de tu app.

Enumerar aprobaciones

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

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 approvals recurso.

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 estableces pageSize, el servidor muestra hasta 100 aprobaciones.

  • pageToken: Es un token de página que se recibe de una llamada de 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&fields=nextPageToken,items(approvalId,status)' \
  -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.