Esta página documenta
github.com/squarecloudofc/sdk-api-go/v3 (v3.0.0), una reescritura del SDK. ¿Vienes de la v2? Lee la guía de migración v2 → v3.Requisitos
- Go 1.22 o más reciente.
- Una clave de API (consulta Clave de API y scopes).
squarecloud.
Instalación
Clave de API y scopes
Crea una clave en squarecloud.app/account/security. El SDK la envía tal cual en el encabezadoAuthorization (sin el prefijo Bearer).
Una clave puede limitarse a scopes (apps:read, apps:deploy, apps:control, ai:chat, …) y a aplicaciones o bases de datos concretas:
- Una llamada fuera de esos límites devuelve un
*APIErrorcon 403MISSING_SCOPEoRESOURCE_NOT_ALLOWED. - Los métodos de listado (
Account.Me,Apps.StatusAll, …) solo devuelven los recursos que la clave puede ver. - Una clave desconocida, revocada o caducada da 401
ACCESS_DENIED.
SQUARECLOUD_API_KEY. Defínela en la terminal donde los ejecutes:
- macOS / Linux
- Windows (PowerShell)
Crear el cliente
main.go en un módulo (go mod init example.com/hello y después el go get de arriba) y ejecuta go run .. Imprime el nombre de tu cuenta y el número de aplicaciones que la clave puede ver:
squarecloud.New(apiKey, opts...) devuelve un *Client y nunca un error. Un *Client es seguro para uso concurrente: créalo una vez y compártelo entre goroutines.
Como New no puede fallar, una clave vacía o compuesta solo por espacios no se rechaza ahí. En su lugar, todas las llamadas salvo Service.Status fallan localmente con INVALID_API_KEY (estado 0) antes de cualquier petición. Este código solo existe en el SDK de Go.
Opciones
Pasa las opciones aNew después de la clave:
El SDK nunca escribe logs. Para trazar las peticiones, envuelve el
http.RoundTripper del cliente que pasas a WithHTTPClient.
Ejecutar los ejemplos
Los ejemplos de las páginas del SDK de Go son fragmentos. Cada uno se ejecuta por sí solo dentro de este programa, que declara losctx, c y appID que usan:
main y después ejecuta goimports -w . para añadir los imports que necesite (fmt, log, time, …). Instálalo con go install golang.org/x/tools/cmd/goimports@latest, o deja que la extensión de Go de tu editor (gopls) añada los imports al guardar. Las páginas que necesitan otros ids, como una base de datos o un workspace, empiezan con su propia versión de este programa.
Módulos
Además de
New y las opciones With*, el paquete exporta las constantes DefaultBaseURL y Version, el tipo APIError con una constante Code* por código de error, constantes tipadas para las entradas enumeradas (DatabaseRedis, GroupView, ResetPassword, SnapshotScopeDatabases, …) y un struct por cada forma de la API, que puedes usar en tu propio código:
Convenciones
Primero el context y el id, de vuelta datos tipados
Todos los métodos reciben primero uncontext.Context y después el id del recurso, y devuelven structs planos (sin métodos ni caché). Las etiquetas json son los nombres de campo de la propia API (created_at, version_id, lastModified, joinedAt, netIO, …), así que la referencia de la API se aplica tal cual: CreatedAt es created_at, VersionID es version_id. Los campos que la API añada más adelante se ignoran, así que nunca rompen la decodificación.
- Las mutaciones solo devuelven un
error, salvo que la API devuelva datos (Envs.*,Deploys.SetWebhook,Deploys.LinkGithubApp,Databases.ResetCredentialsy los métodosCreate). - Un resultado de tipo string es
""cuando la API no envía nada. - Los campos que la API puede enviar como
nullson punteros: comprueba si sonnilantes de usarlos. - Los contadores y los tamaños en bytes son
int64. - Las listas llegan completas en una sola llamada: no hay paginación.
Aplicaciones de workspace
TodoappID acepta también la forma compuesta <appId>-<workspaceId> para actuar sobre una aplicación compartida contigo a través de un workspace. Workspaces.Get y Workspaces.List devuelven ids sin procesar; el id compuesto lo construyes tú:
Los ids se codifican
Los ids en la ruta de la URL se codifican con percent-encoding. Un id vacío,. o .. llegaría a otra ruta, así que falla localmente con INVALID_ID (estado 0) antes de enviar nada. Las rutas de workspace envían sus ids en el cuerpo: ahí, el INVALID_ID (400) viene del servidor.
Fechas
Los argumentosstart y end (consulta Red) son valores time.Time, enviados como RFC 3339 en UTC (segundos enteros). En las respuestas, los strings ISO 8601 de la API se decodifican a time.Time, y los campos que la API envía como milisegundos Unix siguen siendo números (Plan.Duration y Uptime como *int64, FileEntry.LastModified como *float64): conviértelos con time.UnixMilli.
Timeouts
- El deadline por defecto se aplica solo cuando
ctxno tiene deadline. Un deadline enctxsiempre gana, sea más corto o más largo que el valor por defecto, mínimos incluidos. - Un único deadline cubre toda la llamada: cada intento y las esperas entre reintentos.
WithTimeout(0)(o cualquierd <= 0) desactiva todos los deadlines por defecto, incluidos los mínimos de 2 minutos.
ctx, así que puedes limitar o cancelar cualquier llamada:
ctx expira devuelve un *APIError con TIMEOUT, y una cuyo ctx se cancela devuelve NETWORK_ERROR, ambos con estado 0. Ambos envuelven el error del context, así que errors.Is(err, context.DeadlineExceeded) y errors.Is(err, context.Canceled) funcionan. Un bucle de tiempo real devuelve en cambio el ctx.Err() sin envolver.
Cuenta
c.Account.Me(ctx) devuelve el usuario autenticado junto con las aplicaciones y bases de datos que la clave puede ver.
c.Account.Snapshots(ctx, scope) lista todos los snapshots de la cuenta: consulta Snapshots.
Estado de la plataforma
c.Service.Status(ctx) devuelve el estado público de la plataforma. La ruta no necesita clave, y es el único método que también funciona en un cliente creado con una clave vacía.
unknown significa que la propia comprobación no pudo ejecutarse: no es una prueba de una caída.
Próximos pasos
Gestión de aplicaciones
Estado, ciclo de vida, logs y métricas.
Errores
Clase de error, reintentos y límites de tasa.
Introducción a la API
URL base, autenticación y una primera solicitud.
Inicio rápido de la CLI
Haz deploy y gestiona aplicaciones desde la terminal.

