> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Sheets API for Laravel

> Usa la API de Google Sheets v4 en Laravel. Interfaz fluida e intuitiva.

Paquete para Laravel de la API de Google Sheets v4. Oculta la complejidad de la librería cliente de Google para PHP y ofrece una API con encadenamiento de métodos intuitiva y expresiva.

## Características

* **Compatible con varios métodos de autenticación**: OAuth 2.0 (acceso por usuario), Service Account (comunicación entre servidores), API key (datos públicos).
* **API fluida**: manipula los datos de forma intuitiva con encadenamiento de métodos.
* **Integración con Laravel Collections**: convierte los datos de Google Sheets en Laravel Collections. Facilita el procesamiento de arrays.
* **Extensibilidad**: puedes añadir métodos personalizados al Facade con el sistema de macros.
* **Integración con Google Drive**: gestión y listado de hojas de cálculo.

## Escenarios habituales de uso

* **Dashboards de usuario**: mostrar y manipular datos de Google Sheets.
* **Importación/exportación de datos**: migración masiva de datos entre una app Laravel y Google Sheets.
* **Generación automática de informes**: generar y actualizar informes programáticamente.
* **Aplicaciones multiusuario**: cada usuario administra sus propias Google Sheets.

## Filosofía de diseño

El objetivo principal de este paquete es la **lectura desde Google Sheets**. En lugar de especificar condiciones detalladas antes de leer, primero se obtienen todos los datos como Laravel Collection y luego se procesan en el lado de Laravel.

## Requisitos del sistema

* PHP >= 8.3
* Laravel >= 12.0

## Instalación

<Steps>
  <Step title="Instala con Composer">
    ```bash theme={null}
    composer require revolution/laravel-google-sheets
    ```
  </Step>

  <Step title="Publica el archivo de configuración">
    ```bash theme={null}
    php artisan vendor:publish --tag="google-config"
    ```
  </Step>

  <Step title="Habilita las APIs de Google">
    Activa las siguientes APIs en la [Google Cloud Console](https://console.cloud.google.com/):

    * **Google Sheets API**
    * **Google Drive API**
  </Step>

  <Step title="Selecciona y configura el método de autenticación">
    Elige entre tres métodos y configúralo:

    * [Service Account](/es/packages/laravel-google-sheets/service-account): para comunicación entre servidores y tareas automatizadas.
    * [OAuth 2.0](/es/packages/laravel-google-sheets/oauth): para acceso por usuario.
    * API key: solo para datos públicos.
  </Step>
</Steps>

## Selección del método de autenticación

| Método              | Uso                                           | Interacción del usuario    | Alcance del acceso        | Dificultad |
| ------------------- | --------------------------------------------- | -------------------------- | ------------------------- | ---------- |
| **Service Account** | Comunicación entre servidores, automatización | No necesaria               | Hojas compartidas         | Media      |
| **OAuth 2.0**       | Aplicaciones orientadas al usuario            | Se requiere consentimiento | Hojas propias del usuario | Alta       |
| **API key**         | Solo datos públicos                           | No necesaria               | Solo hojas públicas       | Baja       |

## Uso básico

Considera el siguiente ejemplo de estructura de hoja de cálculo.

| id | name  | mail  |
| -- | ----- | ----- |
| 1  | name1 | mail1 |
| 2  | name2 | mail2 |

Spreadsheet URL: `https://docs.google.com/spreadsheets/d/{spreadsheetID}/...`

Obtén el `spreadsheetId` desde la URL.

### Service Account

Si usas autenticación con Service Account, no es necesario configurar el token.

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

// La autenticación con Service Account se realiza automáticamente en la configuración
$values = Sheets::spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name2', 'mail2']
// ]
```

### OAuth

Con autenticación OAuth, debes configurar el access token del usuario.

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

$user = $request->user();

$token = [
    'access_token'  => $user->access_token,
    'refresh_token' => $user->refresh_token,
    'expires_in'    => $user->expires_in,
    'created'       => $user->updated_at->getTimestamp(),
];

// all() devuelve un array
$values = Sheets::setAccessToken($token)->spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name1', 'mail2']
// ]
```

### Obtener los valores usando la cabecera como clave (recomendado)

La conversión a colecciones es sencilla y luego puedes procesar los datos con flexibilidad, así que recomendamos este método.

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

// get() devuelve una Laravel Collection
$rows = Sheets::sheet('Sheet 1')->get();

$header = $rows->pull(0);
$values = Sheets::collection(header: $header, rows: $rows);
$values->toArray()
// [
//   ['id' => '1', 'name' => 'name1', 'mail' => 'mail1'],
//   ['id' => '2', 'name' => 'name2', 'mail' => 'mail2']
// ]
```

Blade

```php theme={null}
@foreach($values as $value)
  {{ data_get($value, 'name') }}
@endforeach
```

### Uso de la notación A1

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

$values = Sheets::sheet('Sheet 1')->range('A1:B2')->all();
// [
//   ['id', 'name'],
//   ['1', 'name1'],
// ]
```

### Sobre la notación A1

La notación A1 es la forma estándar de indicar celdas o rangos en Google Sheets (por ejemplo, "A1", "A1:B2").

* "A1" hace referencia a la celda de la columna A, fila 1.
* "A1:B2" indica el rango (rectángulo) desde A1 hasta B2.
* "A:B" indica todas las filas de las columnas A y B.

Si no estás familiarizado con la notación A1, o si el rango es dinámico o complejo, a menudo es más sencillo obtener todos los datos y luego procesarlos o filtrarlos con las colecciones de Laravel.

## Próximos pasos

* [Autenticación con Service Account](/es/packages/laravel-google-sheets/service-account): el método más habitual.
* [Autenticación con OAuth 2.0](/es/packages/laravel-google-sheets/oauth): acceso por usuario.
* [laravel-google-sheets](https://github.com/invokable/laravel-google-sheets)
* [Proyecto de demostración](https://github.com/invokable/google-sheets-project): ejemplos compatibles desde Laravel 5.5 hasta 13.
* [Paquete relacionado: Google Search Console API for Laravel](https://github.com/invokable/laravel-google-searchconsole)

## Demo en vivo

Puedes ver el funcionamiento real en la [demo de Laravel Google Sheets](https://sheets.kawax.biz/).


## Related topics

- [Autenticación OAuth 2.0 - Google Sheets API for Laravel](/es/packages/laravel-google-sheets/oauth.md)
- [Autenticación Service Account - Google Sheets API for Laravel](/es/packages/laravel-google-sheets/service-account.md)
- [Laravel Socialite (autenticación social)](/es/socialite.md)
- [Laravel Cashier (Stripe)](/es/cashier.md)
- [Laravel Console Starter](/es/packages/laravel-console-starter/index.md)