Append Row to a Spreadsheet — Google Sheets

Descripción

Agrega una fila (o varias) al final de los datos existentes en una hoja específica de un spreadsheet, utilizando la API de Google Sheets.

Parámetros de Entrada

Campo	Tipo	Requerido	Descripción
spreadsheet_id	String	Sí	ID del spreadsheet destino.
sheet	Número	Sí	ID numérico de la hoja (gid / tab) dentro del spreadsheet. (Nota: No es el nombre visible de la pestaña).
value	Variable	Sí	Datos a insertar en la hoja. Ver sección Formato de datos aceptado.

Formato de Datos Aceptado

El campo value admite los siguientes formatos de datos:

• Valor simple (String o Número): Se inserta como una única fila conteniendo una sola celda.
• Array unidimensional ([a, b, c]): Se inserta como una sola fila con los valores distribuidos en columnas consecutivas.
• Array bidimensional ([[a, b], [c, d]]): Cada sub-array interno representa una nueva fila independiente.

Comportamiento de Inserción

• Ubicación: Los datos se insertan siempre inmediatamente después de la última fila que contenga datos dentro de la hoja.
• Rango de columnas: Soporta columnas desde la A hasta la Z.

Respuesta Exitosa

Ejemplo de respuesta (JSON)

{
  "spreadsheetId": "1M0d-fTEnS9fWMfuAQFhrUb3sC1f7otykEpifSB4p3ff",
  "tableRange": "'Hoja 1'!A1:C11",
  "updates": {
    "spreadsheetId": "1M0d-fTEnS9fWMfuAQFhrUb3sC1f7otykEpifSB4p3ff",
    "updatedRange": "'Hoja 1'!A12:C12",
    "updatedRows": 1,
    "updatedColumns": 3,
    "updatedCells": 3
  }
}

Detalle de Campos de la Respuesta

Campo	Tipo	Descripción
spreadsheetId	String	ID del spreadsheet afectado.
tableRange	String	Rango detectado por Google Sheets como la tabla existente antes de la inserción.
updates.updatedRange	String	Rango exacto de celdas donde se escribieron los nuevos datos.
updates.updatedRows	Número	Cantidad de filas insertadas.
updates.updatedColumns	Número	Cantidad de columnas escritas.
updates.updatedCells	Número	Cantidad total de celdas modificadas.

Manejo de Errores

Todos los casos de error devuelven una estructura con el formato:

{
  "status": false,
  "data": "<mensaje_de_error>"
}

Casos de Error

Situación	Mensaje devuelto en data
Falta el parámetro spreadsheet_id	"Spreadsheet id is required"
Falta el parámetro sheet	"Sheet not found"
Falta el parámetro value	"Values not found"
El valor de sheet no existe en el spreadsheet	"Sheet not found"
spreadsheet_id es inválido	Mensaje de error retornado directamente por la API de Google Sheets.
Sin permisos de acceso sobre el archivo	Mensaje de error retornado directamente por la API de Google Sheets.