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

# SDK de Go: migrar de v3 a v4

> Actualiza el SDK de Go de v3 a v4: la ruta de importación /v4, un Restore de snapshots que informa de una restauración en curso, Metrics con un rango y 409 RESTORE_IN_PROGRESS.

La v4 es una versión con cambios incompatibles porque cambian dos firmas. `Restore` de snapshots ahora te dice si la restauración sigue en curso, y `Metrics` recibe un rango. Todo lo demás se añade encima: dos operaciones nuevas, 69 en total, campos nuevos y códigos de error nuevos.

## De un vistazo

| | v3 | v4 |
| - | - | - |
| Módulo | `github.com/squarecloudofc/sdk-api-go/v3` | `github.com/squarecloudofc/sdk-api-go/v4` |
| Operaciones | 67 | 69, con `Apps.Snapshots.RestoreState` y `Databases.Snapshots.RestoreState` |
| Restauración de snapshots | `Restore(ctx, id, name, versionID) error`. Una restauración que seguía en curso tras unos 90 segundos devolvía `nil`, como si hubiera terminado | `Restore(ctx, id, name, versionID) (SnapshotRestored, error)`. `Pending` es `true` mientras la restauración sigue en curso, y `RestoreState` la sigue |
| Métricas | `Metrics(ctx, id)`, solo para las últimas 24 horas | `Metrics(ctx, id, rng)`, donde `rng` es `""` o `"24h"`, o `"7d"` para puntos por hora con picos |
| `RESTORE_IN_PROGRESS` | HTTP 403 | HTTP 409 |
| `CodeMetricsNotSupported` | Lo envía la API | Obsoleto: la API ya no lo envía |
| Versión de Go y dependencias | Go 1.22, sin dependencias | Sin cambios |

## Ruta de importación

Solo cambia la ruta de importación. `New` y todas las `Option` conservan sus firmas y sus valores por defecto, y el `User-Agent` por defecto pasa a ser `squarecloud-sdk-go/4.0.0`.

```diff theme={"system"}
-import "github.com/squarecloudofc/sdk-api-go/v3"
+import "github.com/squarecloudofc/sdk-api-go/v4"
```

```bash theme={"system"}
go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0
```

## Cambios incompatibles

Los ejemplos de abajo se ejecutan dentro de una función que devuelve un `error`.

### Restauración de snapshots

`Apps.Snapshots.Restore` y `Databases.Snapshots.Restore` devuelven `(SnapshotRestored, error)` en lugar de `error`. Una restauración que tarda más de unos 90 segundos sigue ejecutándose después de que la llamada vuelva. La v3 devolvía `nil` en ese caso, así que quien la llamaba informaba "restaurado" mientras seguía en curso. La v4 devuelve `Pending: true` en ese caso, y `Pending: false` para una restauración terminada.

```go theme={"system"}
// v3
if err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID); err != nil {
	return err
}

// v4
res, err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID)
if err != nil {
	return err
}
for res.Pending { // still running: follow it, never send the restore again
	time.Sleep(10 * time.Second)
	st, err := c.Apps.Snapshots.RestoreState(ctx, appID)
	if err != nil {
		return err
	}
	if st.State == "error" {
		return fmt.Errorf("restore failed: %s", st.Code)
	}
	res.Pending = st.State == "queued" || st.State == "running"
}
```

`RestoreState` informa `queued` o `running` mientras se ejecuta la restauración, con el `Step` actual, y después `success` o `error`, con un `Code`, durante 1 hora tras terminar. Informa `none` pasada esa hora o cuando no hubo ninguna restauración reciente. Admite 30 llamadas por minuto. Consulta [Snapshots](https://docs.squarecloud.app/es/sdks/go/snapshots.md#seguir-una-restauración).

### Métricas

`Apps.Metrics` y `Databases.Metrics` reciben un rango como último argumento. Pasa `""` para mantener el comportamiento de la v3, que cubre las últimas 24 horas.

```go theme={"system"}
// v3
points, err := c.Apps.Metrics(ctx, appID)

// v4
points, err := c.Apps.Metrics(ctx, appID, "") // "" or "24h": the last 24 hours
```

`"7d"` devuelve puntos por hora con la media de la hora y sus picos `CPUMax` y `RAMMax`, en los planes Pro y Enterprise para aplicaciones de 512 MB o más. Los demás planes y las aplicaciones más pequeñas reciben la respuesta de 24 horas sin error, así que comprueba los puntos en lugar de dar por hecho que son 7 días. Cualquier otro rango devuelve 400 `INVALID_PARAMETERS`. En las bases de datos, `"7d"` requiere un plan Pro o Enterprise. Consulta [Métricas](https://docs.squarecloud.app/es/sdks/go/managing_application.md#métricas).

### `RESTORE_IN_PROGRESS` es 409

`RESTORE_IN_PROGRESS` pasó de 403 a 409 al eliminar aplicaciones y bases de datos y al iniciar y detener bases de datos. También es nuevo, como 409, al iniciar, detener y reiniciar aplicaciones y en `Create` y `Restore` de snapshots. Compara solo el código:

```go theme={"system"}
var apiErr *squarecloud.APIError

// v3
if errors.As(err, &apiErr) && apiErr.Status == 403 && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running
}

// v4
if errors.As(err, &apiErr) && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running (HTTP 409)
}
```

## Tipos y campos nuevos

| Tipo | Novedades en la v4 |
| - | - |
| `SnapshotRestored` | Nuevo: `Pending bool`, devuelto por `Restore` |
| `SnapshotRestoreState` | Nuevo: `State`, `Step` y `Code` (`string`), `StartedAt` y `FinishedAt` (`*int64`, ms Unix), devuelto por `RestoreState` |
| `ServiceStatus` | `Incidents []ServiceIncident`, los incidentes y las ventanas de mantenimiento abiertos, y `Components []ServiceComponent`, las partes de la plataforma que no funcionan del todo. `Status` puede ser `"maintenance"`, y `"unknown"` significa que la comprobación no pudo ejecutarse |
| `MetricPoint` | `Disk []int64`, los bytes leídos y escritos desde el último inicio, y `Storage *int64`, los bytes en disco, ambos `nil` en un punto sin lectura. `CPUMax` y `RAMMax *float64`, los picos por hora, solo con `"7d"` |
| `RuntimeStats`, `RuntimeStatsRaw` | `Restoring bool` |
| `DNSRecord` | `Errors []string`, hasta 3 mensajes que dicen por qué un registro aún no está activo, y `Fallback bool`, que marca el único CNAME `_acme-challenge` que puede sustituir a todos los registros TXT de SSL |
| `AnalyticsTimeBucket` | `BytesIn int64` |
| `ChatRequest` | `MaxCompletionTokens int`, que tiene prioridad sobre `MaxTokens` |

Los campos nuevos solo rompen los literales de struct de estos tipos que omiten los nombres de los campos. Usa nombres de campo.

## Errores

* Constantes nuevas: `CodeAIWeeklyLimitReached`, `CodeEnvBusy` (409), `CodeGitBranchDeleted` y `CodeGitRefNotSupported` (solo se envían a los webhooks de push de GitHub), `CodeRestoreInterrupted`, `CodeSnapshotsUnavailable` (503), `CodeSnapshotCorrupt`, `CodeSnapshotInProgress` (409), `CodeSnapshotRestoreProcessing` (se informa como `SnapshotRestored.Pending`, nunca como error), `CodeWriteFailed` y `CodeWrongHost` (421, nunca se devuelve a las llamadas de este SDK).
* `CodeMetricsNotSupported` está obsoleto, pero se mantiene.
* Una restauración puede fallar con más códigos que `SNAPSHOT_RESTORE_FAILED`. Consulta [Snapshots](https://docs.squarecloud.app/es/sdks/go/snapshots.md#restaurar-un-snapshot) para ver la lista completa.
* El SDK no reintenta ninguno de los códigos nuevos. `SNAPSHOTS_UNAVAILABLE` pide esperar unos 30 segundos y `CLUSTER_MAINTENANCE_TRY_LATER` dura minutos, ambos más que las esperas de los reintentos. Un 409 de un recurso ocupado lo decides tú.
* Los errores propios del SDK, `INVALID_API_KEY`, `INVALID_ID` y `FILE_TOO_LARGE`, tienen mensajes nuevos que dicen qué salió mal y cómo resolverlo. Compara `Code`, no `Message`.

Consulta [Errores](https://docs.squarecloud.app/es/sdks/go/errors.md) para ver la referencia completa.

## Cambios de comportamiento

* **Los enlaces de los snapshots caducan tras 1 hora.** Antes duraban 30 días, así que descarga justo después de listar o crear un snapshot. Solo `Create` puede devolver `URL` y `Key` vacíos, con `Pending: false`, cuando la clave de API no tiene `snapshots:read`.
* **Los listados de snapshots** (`Account.Snapshots`, `Apps.Snapshots.List` y `Databases.Snapshots.List`) devuelven 503 `SNAPSHOTS_UNAVAILABLE` en lugar de una lista vacía cuando el almacenamiento de snapshots no puede responder.
* **Métricas.** Las aplicaciones de menos de 512 MB ahora tienen métricas, con un punto cada 10 minutos, donde antes recibían 400 `METRICS_NOT_SUPPORTED`.
* **Variables de entorno.** `Envs.Set`, `Envs.Replace` y `Envs.Delete` devuelven 409 `ENV_BUSY` cuando hay otra escritura en curso. Con una clave de API sin `envs:read`, `Envs.Set` devuelve solo las variables que enviaste, no el conjunto completo, y `Envs.Delete` devuelve un conjunto vacío.
* **Archivos.** `Files.Read` y `Files.Write` pueden devolver 400 `READ_FAILED` y `WRITE_FAILED`, y `Commit` puede devolver 403 `BLOCKED_PATH`.
* **Subidas en paralelo.** La API limita cuántas subidas grandes puede enviar una cuenta a la vez. Superar el límite devuelve 429 `RATE_LIMITED`, que el SDK nunca reintenta.
* **IA.** Un 429 de `AI.Chat` puede ser `weekly_limit_reached`.
* **User-Agent** es `squarecloud-sdk-go/4.0.0`.

## Lista de comprobación

**1. Cambia la ruta de importación**

Importa `github.com/squarecloudofc/sdk-api-go/v4` en todas partes y ejecuta `go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0`.

**2. Sigue las restauraciones pendientes**

Sustituye `err := c.Apps.Snapshots.Restore(...)` por `res, err := ...`. Cuando `res.Pending` sea `true`, consulta `RestoreState`, por ejemplo cada 10 segundos, hasta que `State` sea `success` o `error`. Nunca vuelvas a enviar la restauración.

**3. Pasa un rango a Metrics**

Añade `""`, `"24h"` o `"7d"` como último argumento de `Apps.Metrics` y `Databases.Metrics`.

**4. Compara 409 RESTORE\_IN\_PROGRESS**

Compara `409` donde comparabas `403`, o compara solo el código.

**5. Gestiona 503 SNAPSHOTS\_UNAVAILABLE**

Gestiónalo en los listados de snapshots, en lugar de interpretar una lista vacía como "no hay snapshots".

**6. Compara códigos, no mensajes**

Comprueba `Code` dondequiera que compararas el `Message` de `INVALID_API_KEY`, `INVALID_ID` o `FILE_TOO_LARGE`.

## Próximos pasos

> [card] [Cliente](https://docs.squarecloud.app/es/sdks/go/client.md)
>
> Instala el SDK y crea un cliente.

> [card] [Snapshots](https://docs.squarecloud.app/es/sdks/go/snapshots.md)
>
> Crea, restaura y sigue snapshots.

> [card] [Errores](https://docs.squarecloud.app/es/sdks/go/errors.md)
>
> Clase de error, reintentos y límites de tasa.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.