Client

Requisitos

Go 1.24 ou mais recente
Zero dependências externas — o SDK é construído apenas sobre a biblioteca padrão do Go
Uma chave de API válida — solicite uma no Dashboard da Square Cloud em Minha Conta → Regenerar API/CLI KEY

Instalação

go get github.com/squarecloudofc/sdk-api-go/v2

O módulo é distribuído com dois pacotes:

Pacote	Caminho de import	Conteúdo
`rest`	`github.com/squarecloudofc/sdk-api-go/v2/rest`	Client HTTP, interfaces de recursos, opções de requisição, erros, stream SSE
`squarecloud`	`github.com/squarecloudofc/sdk-api-go/v2/squarecloud`	Todos os tipos e structs de requisição/resposta

Instanciando o client

package main

import (
	"fmt"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v2/rest"
)

func main() {
	client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
	defer client.Close()

	api := rest.New(client)

	user, err := api.SelfUser()
	if err != nil {
		panic(err)
	}
	fmt.Println(user.Name)
}

rest.NewClient(token, opts...) constrói o client HTTP subjacente; rest.New(client) o encapsula em rest.Rest, a interface que expõe todos os recursos. Sempre use defer client.Close() para liberar conexões ociosas.

Configuração do client (`ConfigOpt`)

rest.NewClient aceita ConfigOpts opcionais após o token:

Opção	Padrão	Descrição
`rest.WithLogger(*slog.Logger)`	descartado	Logger estruturado para depurar requisições/respostas
`rest.WithHTTPClient(*http.Client)`	timeout de 30s	`*http.Client` customizado (proxies, transports, timeouts)
`rest.WithURL(string)`	`https://api.squarecloud.app/v2`	URL base da API
`rest.WithUserAgent(string)`	padrão do SDK	Header `User-Agent` customizado

client := rest.NewClient(
	os.Getenv("SQUARECLOUD_API_KEY"),
	rest.WithLogger(slog.Default()),
	rest.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)

Módulos

rest.Rest incorpora uma interface por domínio de recurso, além dos métodos de usuário e de status documentados nesta página:

Interface	Cobertura	Documentação
`Applications`	Gerenciamento, upload, arquivos, envs, snapshots, deploys, rede, tempo real	Gerenciando aplicações
`Databases`	Criação, gerenciamento, credenciais e snapshots	Bancos de dados
`Workspaces`	Criação, membros, aplicações compartilhadas	Workspaces

Obtendo o usuário autenticado

api.SelfUser() retorna um squarecloud.User com os detalhes da conta e o plano atual.

user, err := api.SelfUser()
if err != nil {
	panic(err)
}

fmt.Println(user.ID)       // "abcdef0123456789abcdef01"
fmt.Println(user.Name)     // "John Doe"
fmt.Println(user.Email)    // "john@example.com"
fmt.Println(user.Locale)   // "en-US"
fmt.Println(user.Plan.Name)             // ex.: "standard"
fmt.Println(user.Plan.Duration)         // duração do plano, ex.: "monthly"
fmt.Println(user.Plan.Memory.Limit)     // MB
fmt.Println(user.Plan.Memory.Available) // MB
fmt.Println(user.Plan.Memory.Used)      // MB
fmt.Println(user.CreatedAt)

Campo	Tipo	Descrição
`ID`	`string`	ID do usuário (24 chars hex)
`Name`	`string`	Nome de exibição
`Email`	`string`	E-mail da conta
`Locale`	`string`	Localidade preferida, ex.: `"en-US"`
`Plan`	`squarecloud.UserPlan`	`Name`, `Memory{Limit, Available, Used}` (MB) e `Duration`
`CreatedAt`	`string`	Data de criação da conta

Listando suas aplicações e bancos de dados

api.GetApplications() e api.GetDatabases() listam tudo que você possui através do endpoint /users/me, retornando descritores compactos squarecloud.UserApplication / squarecloud.UserDatabase:

apps, err := api.GetApplications()
if err != nil {
	panic(err)
}
for _, app := range apps {
	fmt.Printf("%s (%s) — %dMB\n", app.Name, app.ID, app.RAM)
}

dbs, err := api.GetDatabases()
if err != nil {
	panic(err)
}
for _, db := range dbs {
	fmt.Printf("%s (%s)\n", db.Name, db.ID)
}

Para buscar o registro completo de um único recurso, use GetApplication / GetDatabase — veja Gerenciando aplicações e Bancos de dados.

Listando histórico de snapshots da conta

api.UserSnapshots(scope) retorna todos os snapshots que você possui para um determinado domínio:

appSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeApplications)
if err != nil {
	panic(err)
}

dbSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeDatabases)
if err != nil {
	panic(err)
}

Veja Snapshots para detalhes sobre os payloads de snapshot.

Status da plataforma

api.ServiceStatus() expõe a saúde agregada da plataforma (os mesmos dados exibidos na página pública de status).

status, err := api.ServiceStatus()
if err != nil {
	panic(err)
}

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // resumo legível

Diferente da maioria dos endpoints v2, essa rota não encapsula o payload no envelope padrão { status, code, response } — ela responde com { status, message } diretamente.

Opções de requisição

Todos os métodos aceitam ...rest.RequestOpts ao final para customizar a requisição individual:

Opção	Descrição
`rest.WithContext(ctx)`	Anexa um `context.Context` para cancelamento ou deadlines
`rest.WithQueryParam(key, value)`	Adiciona um parâmetro de query
`rest.WithHeader(key, value)`	Define um header da requisição
`rest.WithToken(token)`	Sobrescreve o token de autenticação apenas para essa requisição

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

user, err := api.SelfUser(rest.WithContext(ctx))
if err != nil {
	panic(err)
}

Tratamento de erros

Qualquer resposta não-2xx é retornada como um *rest.APIError expondo StatusCode, Code e Message. Desembrulhe com o idiomático errors.As:

app, err := api.GetApplication("invalid-id")
if err != nil {
	var apiErr *rest.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode) // ex.: 404
		fmt.Println(apiErr.Code)       // ex.: "APP_NOT_FOUND"
		fmt.Println(apiErr.Message)
	}
	return
}

Dois helpers simplificam as verificações mais comuns:

rest.ErrorCode(err) string — retorna o código de erro da API (ou "" quando o erro não é um *rest.APIError)
rest.IsRateLimit(err) bool — informa se o erro é algum dos códigos de rate limit (KEEP_CALM, RATE_LIMIT, RATE_LIMIT_EXCEEDED, RATELIMIT, DELAY_NOW)

if err != nil {
	if rest.IsRateLimit(err) {
		time.Sleep(5 * time.Second)
		// tentar novamente...
	}

	switch rest.ErrorCode(err) {
	case "APP_NOT_FOUND":
		fmt.Println("a aplicação não existe")
	case "ACCESS_DENIED":
		fmt.Println("chave de API inválida")
	}
}

Os códigos de erro são os mesmos usados pelo @squarecloud/api-types — veja a tabela completa de códigos na referência do SDK de JS.

Serviços

Runtimes

Plataforma

Solução de Problemas

CLI

SDKs

Changelog

Requisitos

Instalação

Instanciando o client

Configuração do client (`ConfigOpt`)

Módulos

Obtendo o usuário autenticado

Listando suas aplicações e bancos de dados

Listando histórico de snapshots da conta

Status da plataforma

Opções de requisição

Tratamento de erros

​Requisitos

​Instalação

​Instanciando o client

​Configuração do client (ConfigOpt)

​Módulos

​Obtendo o usuário autenticado

​Listando suas aplicações e bancos de dados

​Listando histórico de snapshots da conta

​Status da plataforma

​Opções de requisição

​Tratamento de erros

Requisitos

Instalação

Instanciando o client

Configuração do client (`ConfigOpt`)

Módulos

Obtendo o usuário autenticado

Listando suas aplicações e bancos de dados

Listando histórico de snapshots da conta

Status da plataforma

Opções de requisição

Tratamento de erros