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

# Autenticación Service Account - Google Sheets API for Laravel

> Configura la autenticación Service Account de la API de Google Sheets. Ideal para comunicación entre servidores.

La autenticación con Service Account es la mejor opción cuando tu aplicación accede a Google Sheets de servidor a servidor. No requiere interacción del usuario: la propia aplicación opera sobre las hojas de cálculo. Es adecuada para tareas automatizadas y trabajos en segundo plano.

## Casos de uso

* **Acceso servidor a servidor** — la app accede a Sheets sin intervención del usuario
* **Sistemas automatizados** — trabajos en segundo plano, tareas cron, informes automáticos
* **Hojas de cálculo fijas** — controlas hojas de cálculo concretas
* **Entornos de producción** — funcionan de forma fiable sin flujos de consentimiento del usuario

## Requisitos previos

* Un proyecto en Google Cloud Console
* Habilita la API de Google Sheets y la API de Google Drive
* Permisos de administrador del proyecto

## Configuración

<Steps>
  <Step title="Crea un proyecto en Google Cloud">
    1. Accede a [Google Cloud Console](https://console.cloud.google.com/)
    2. Crea un proyecto nuevo o selecciona uno existente
    3. Anota el ID del proyecto
  </Step>

  <Step title="Habilita las API necesarias">
    1. Ve a **APIs & Services** > **Library**
    2. Busca y habilita las siguientes API:
       * **Google Sheets API**
       * **Google Drive API**
  </Step>

  <Step title="Crea una Service Account">
    1. Ve a **APIs & Services** > **Credentials**
    2. Haz clic en **Create Credentials** > **Service Account**
    3. Introduce los detalles de la Service Account:
       * **Service account name**: un nombre descriptivo (por ejemplo, «Laravel Sheets App»)
       * **Service account ID**: se genera automáticamente
       * **Description**: opcional
    4. Haz clic en **Create and Continue**
    5. Omite ambas secciones opcionales y haz clic en **Done**
  </Step>

  <Step title="Genera la clave de la Service Account">
    1. En la página **Credentials**, haz clic en la Service Account que creaste
    2. Ve a la pestaña **Keys**
    3. Haz clic en **Add Key** > **Create new key**
    4. Selecciona el formato de clave **JSON**
    5. Haz clic en **Create**
    6. El archivo JSON se descargará automáticamente
  </Step>

  <Step title="Guarda el archivo JSON">
    1. Mueve el archivo JSON descargado a `storage/app/`
    2. Renómbralo a `google-service-account.json`
    3. **Importante**: añádelo a `.gitignore` para excluirlo del control de versiones

    ```bash theme={null}
    # Añadir a .gitignore
    storage/app/google-service-account.json
    ```
  </Step>

  <Step title="Configura el archivo .env">
    Añade lo siguiente a `.env`:

    ```env theme={null}
    GOOGLE_SERVICE_ENABLED=true
    GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION=storage/app/google-service-account.json
    ```
  </Step>

  <Step title="Configura los scopes en config/google.php">
    ```php theme={null}
    'scopes' => [
        \Google\Service\Sheets::SPREADSHEETS,
        \Google\Service\Drive::DRIVE,
    ],
    ```
  </Step>

  <Step title="Comparte las hojas de cálculo">
    Para cada hoja de cálculo de Google Sheets:

    1. Ábrela en Google Sheets
    2. Haz clic en el botón **Compartir**
    3. Copia el campo `client_email` del archivo JSON
    4. Compártela con esa dirección de correo (por ejemplo, `your-service-account@your-project-id.iam.gserviceaccount.com`)
    5. Selecciona los permisos:
       * **Lector** — solo lectura
       * **Editor** — lectura y escritura
       * **Propietario** — acceso completo (no recomendado)
  </Step>
</Steps>

## Uso

Una vez configurada, la Service Account se usará automáticamente. No es necesario configurar tokens de acceso.

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

// La Service Account se utiliza automáticamente
$values = Sheets::spreadsheet('your-spreadsheet-id')
    ->sheet('Sheet1')
    ->all();

// Referencia por nombre de la hoja de cálculo (requiere acceso a la API de Drive)
$values = Sheets::spreadsheetByTitle('My Spreadsheet')
    ->sheet('Sheet1')
    ->all();
```

## Buenas prácticas de seguridad

### 1. Limita los permisos de la Service Account

* Comparte solo las hojas de cálculo necesarias
* Utiliza **Editor** en lugar de **Propietario**
* Audita los permisos de acceso con regularidad

### 2. Almacena la clave de forma segura

* No incluyas la clave de la Service Account en el control de versiones
* Asegúrate de excluirla en `.gitignore`
* En producción, guárdala en un lugar seguro fuera de la raíz del servidor web
* Rota las claves periódicamente

### 3. Despliegue en producción

Medidas de seguridad adicionales:

* Guarda la clave JSON en un lugar seguro fuera de la raíz web
* Utiliza Service Accounts distintas por entorno (desarrollo, staging, producción)
* Supervisa el uso de estas cuentas en Google Cloud Console
* Registra y alerta sobre actividad sospechosa

## Referencia de variables de entorno

| Variable                               | Descripción                                   | Ejemplo                                   |
| -------------------------------------- | --------------------------------------------- | ----------------------------------------- |
| `GOOGLE_SERVICE_ENABLED`               | Habilita la autenticación con Service Account | `true`                                    |
| `GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION` | Ruta al archivo JSON                          | `storage/app/google-service-account.json` |

## Configuración avanzada

### Almacenar la cadena JSON en una variable de entorno

En lugar de guardar el archivo JSON como archivo independiente, puedes almacenar la cadena JSON como variable de entorno. Es adecuado para entornos CI/CD como GitHub Actions.

**Paso 1: añade la cadena JSON al `.env`**

```env theme={null}
GOOGLE_SERVICE_ENABLED=true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION='{"type": "service_account", "project_id": "your-project-id", ...}'
```

**Paso 2: decodifica la cadena JSON en `config/google.php`**

```php theme={null}
// config/google.php
'service' => [
    'enable' => env('GOOGLE_SERVICE_ENABLED', false),
    'file' => json_decode(env('GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION', ''), true),
],
```

Con este método no necesitas guardar el archivo por separado y puedes gestionarlo íntegramente a través de las variables de entorno de tu pipeline de CI/CD.

## Solución de problemas

### Errores frecuentes

**Error «caller does not have permission»**

* Comprueba que la hoja de cálculo esté compartida con la dirección de correo de la Service Account
* Para operaciones de escritura, verifica que los permisos sean **Editor** o superiores

**Error «File not found»**

* Verifica que la ruta al archivo JSON sea correcta
* Comprueba que el archivo exista y que el servidor web pueda leerlo

**Error «API not enabled»**

* Verifica en Google Cloud Console que la API de Google Sheets y la API de Google Drive estén habilitadas
* Espera unos minutos tras habilitar las API

**Error «Invalid credentials»**

* Comprueba que el archivo de clave JSON sea válido y no esté corrupto
* Verifica que la Service Account no haya sido eliminada ni deshabilitada
* Comprueba que el ID del proyecto coincida con el proyecto de Google Cloud

### Prueba de la configuración

Ruta de prueba para verificar la configuración de la Service Account:

```php theme={null}
// routes/web.php
Route::get('/test-sheets', function () {
    try {
        $sheets = Sheets::spreadsheetList();
        return response()->json([
            'status' => 'success',
            'message' => 'La autenticación Service Account funciona correctamente',
            'spreadsheet_count' => count($sheets)
        ]);
    } catch (\Exception $e) {
        return response()->json([
            'status' => 'error',
            'message' => $e->getMessage()
        ]);
    }
});
```

Accede a esta ruta de prueba para comprobar que la autenticación con Service Account está configurada correctamente.


## Related topics

- [Google Sheets API for Laravel](/es/packages/laravel-google-sheets/index.md)
- [Autenticación OAuth 2.0 - Google Sheets API for Laravel](/es/packages/laravel-google-sheets/oauth.md)
- [Laravel Socialite (autenticación social)](/es/socialite.md)
- [Implementación de un guard de autenticación personalizado](/es/advanced/custom-auth-guard.md)
- [Laravel Sanctum (autenticación con API tokens)](/es/sanctum.md)